https://docs.moodle.org/4x/sv/api.php?action=feedcontributions&feedformat=atom&user=DonalmMoodleDocs - Användarbidrag [sv]2026-04-21T03:09:51ZAnvändarbidragMediaWiki 1.43.5https://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=33196Web services API2008-03-05T03:31:06Z<p>Donalm: /* Tell us! */</p>
<hr />
<div>This page describes internals of how to add a new web service to Moodle. If you are just trying to connect to Moodle to do some stuff then come to the [[Development:Web_services]] page and help us build up a standard set of functions.<br />
<br />
== Overview ==<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket science. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'dangerous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system/listMethods<br />
* system/methodSignature<br />
* system/methodHelp<br />
* system/listServices<br />
Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system/keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php. Note that the _name and _description suffixes are required:<br />
<br />
$string['yummy_beer_name'] = 'Yummy Beer';<br />
$string['yummy_beer_description'] = 'A service to bribe your sysadmin with promises of gourmet beer.';<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection recognise your edits.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll almost always need some kind of wrapper function to establish a security context or identify the server that's making the request. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function, but it must be named with a prefix of the module name, e.g. forum_mnet_publishes. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_sp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
Remember that if you're writing such a function for a module, the function name must be prefixed with your module name, e.g. modulename_mnet_publishes.<br />
<br />
The name that you give your service is entirely up to you, but you need to create a language file in (for example) lang/en_utf8/mod_forum.php to store your service name and description, for example:<br />
<br />
$string['sso_idp_name'] = 'SSO (Identity Provider)';<br />
$string['sso_idp_description'] = 'A description of the SSO IDP service that allows an admin to know if he needs it or not.';<br />
<br />
Note that your service name (in this example 'sso_idp') is suffixed with _name and _description.<br />
<br />
Turning back to the mnet_publishes function, your associative array has an 'apiversion' key, that allows you to provide more than one version of your API. This is really provided for future use, and isn't implemented in the code yet. We anticipate that eventually APIs will have to change, and this should allow newer Moodles to still be able to communicate with older Moodles. While this is unavoidable, it's something that we want to put of for as long as possible.<br />
<br />
Finally, you provide a list of method or function names that constitute the service. When an admin enables this service for a host, he's really permitting the host to remotely call the methods or functions that you list here.<br />
<br />
Calling a function remotely will require your XML-RPC client to pass something like this to the Moodle XML-RPC server as the function name:<br />
"mod/forum/rpclib.php/somefunction"<br />
<br />
==Other Implementations==<br />
XML-RPC won't work for everyone. If you're planning a REST or SOAP service, please consider putting your work into mnet/soap or mnet/rest, so that it's alongside mnet/xmlrpc. The work we've done in the mnet directory might be useful to you as well, so rather than re-invent the wheel, have a look at our code to see if it meets any of your needs.<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Mahoodle&diff=32186Mahoodle2008-02-14T13:22:07Z<p>Donalm: Configure SSO for Moodle and Mahara</p>
<hr />
<div>A PDF has been created to help users in configuring Moodle and Mahara to network together, supporting Single-Sign-On (SSO). The 3MB document titled "Mahoodle" has been uploaded to the page here:<br />
https://eduforge.org/docman/?group_id=176</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25544Web services API2007-08-02T06:40:19Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system/listMethods<br />
* system/methodSignature<br />
* system/methodHelp<br />
* system/listServices<br />
Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system/keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php. Note that the _name and _description suffixes are required:<br />
<br />
$string['yummy_beer_name'] = 'Yummy Beer';<br />
$string['yummy_beer_description'] = 'A service to bribe your sysadmin with promises of gourmet beer.';<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection recognise your edits.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll almost always need some kind of wrapper function to establish a security context or identify the server that's making the request. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function, but it must be named with a prefix of the module name, e.g. forum_mnet_publishes. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_sp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
Remember that if you're writing such a function for a module, the function name must be prefixed with your module name, e.g. modulename_mnet_publishes.<br />
<br />
The name that you give your service is entirely up to you, but you need to create a language file in (for example) lang/en_utf8/mod_forum.php to store your service name and description, for example:<br />
<br />
$string['sso_idp_name'] = 'SSO (Identity Provider)';<br />
$string['sso_idp_description'] = 'A description of the SSO IDP service that allows an admin to know if he needs it or not.';<br />
<br />
Note that your service name (in this example 'sso_idp') is suffixed with _name and _description.<br />
<br />
Turning back to the mnet_publishes function, your associative array has an 'apiversion' key, that allows you to provide more than one version of your API. This is really provided for future use, and isn't implemented in the code yet. We anticipate that eventually APIs will have to change, and this should allow newer Moodles to still be able to communicate with older Moodles. While this is unavoidable, it's something that we want to put of for as long as possible.<br />
<br />
Finally, you provide a list of method or function names that constitute the service. When an admin enables this service for a host, he's really permitting the host to remotely call the methods or functions that you list here.<br />
<br />
Calling a function remotely will require your XML-RPC client to pass something like this to the Moodle XML-RPC server as the function name:<br />
"mod/forum/rpclib.php/somefunction"<br />
<br />
==Other Implementations==<br />
XML-RPC won't work for everyone. If you're planning a REST or SOAP service, please consider putting your work into mnet/soap or mnet/rest, so that it's alongside mnet/xmlrpc. The work we've done in the mnet directory might be useful to you as well, so rather than re-invent the wheel, have a look at our code to see if it meets any of your needs.<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25542Web services API2007-08-02T02:10:03Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system/listMethods<br />
* system/methodSignature<br />
* system/methodHelp<br />
* system/listServices<br />
Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system/keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php. Note that the _name and _description suffixes are required:<br />
<br />
$string['yummy_beer_name'] = 'Yummy Beer';<br />
$string['yummy_beer_description'] = 'A service to bribe your sysadmin with promises of gourmet beer.';<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection recognise your edits.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll almost always need some kind of wrapper function to establish a security context or identify the server that's making the request. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_sp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
The name that you give your service is entirely up to you, but you need to create a language file in (for example) lang/en_utf8/mod_forum.php to store your service name and description, for example:<br />
<br />
$string['sso_idp_name'] = 'SSO (Identity Provider)';<br />
$string['sso_idp_description'] = 'A description of the SSO IDP service that allows an admin to know if he needs it or not.';<br />
<br />
Note that your service name (in this example 'sso_idp') is suffixed with _name and _description.<br />
<br />
Turning back to the mnet_publishes function, your associative array has an 'apiversion' key, that allows you to provide more than one version of your API. This is really provided for future use, and isn't implemented in the code yet. We anticipate that eventually APIs will have to change, and this should allow newer Moodles to still be able to communicate with older Moodles. While this is unavoidable, it's something that we want to put of for as long as possible.<br />
<br />
Finally, you provide a list of method or function names that constitute the service. When an admin enables this service for a host, he's really permitting the host to remotely call the methods or functions that you list here.<br />
<br />
Calling a function remotely will require your XML-RPC client to pass something like this to the Moodle XML-RPC server as the function name:<br />
"mod/forum/rpclib.php/somefunction"<br />
<br />
==Other Implementations==<br />
XML-RPC won't work for everyone. If you're planning a REST or SOAP service, please consider putting your work into mnet/soap or mnet/rest, so that it's alongside mnet/xmlrpc. The work we've done in the mnet directory might be useful to you as well, so rather than re-invent the wheel, have a look at our code to see if it meets any of your needs.<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25541Web services API2007-08-02T02:08:49Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system/listMethods<br />
* system/methodSignature<br />
* system/methodHelp<br />
* system/listServices<br />
Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system/keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php. Note that the _name and _description suffixes are required:<br />
<br />
$string['sso_idp_name'] = 'SSO (Identity Provider)';<br />
$string['sso_idp_description'] = 'A description of the SSO IDP service that allows an admin to know if he needs it or not.';<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection recognise your edits.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll almost always need some kind of wrapper function to establish a security context or identify the server that's making the request. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_sp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
The name that you give your service is entirely up to you, but you need to create a language file in (for example) lang/en_utf8/mod_forum.php to store your service name and description, for example:<br />
<br />
$string['sso_idp_name'] = 'SSO (Identity Provider)';<br />
$string['sso_idp_description'] = 'A description of the SSO IDP service that allows an admin to know if he needs it or not.';<br />
<br />
Note that your service name (in this example 'sso_idp') is suffixed with _name and _description.<br />
<br />
Turning back to the mnet_publishes function, your associative array has an 'apiversion' key, that allows you to provide more than one version of your API. This is really provided for future use, and isn't implemented in the code yet. We anticipate that eventually APIs will have to change, and this should allow newer Moodles to still be able to communicate with older Moodles. While this is unavoidable, it's something that we want to put of for as long as possible.<br />
<br />
Finally, you provide a list of method or function names that constitute the service. When an admin enables this service for a host, he's really permitting the host to remotely call the methods or functions that you list here.<br />
<br />
Calling a function remotely will require your XML-RPC client to pass something like this to the Moodle XML-RPC server as the function name:<br />
"mod/forum/rpclib.php/somefunction"<br />
<br />
==Other Implementations==<br />
XML-RPC won't work for everyone. If you're planning a REST or SOAP service, please consider putting your work into mnet/soap or mnet/rest, so that it's alongside mnet/xmlrpc. The work we've done in the mnet directory might be useful to you as well, so rather than re-invent the wheel, have a look at our code to see if it meets any of your needs.<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25540Web services API2007-08-02T01:11:29Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system/listMethods<br />
* system/methodSignature<br />
* system/methodHelp<br />
* system/listServices<br />
Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system/keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection recognise your edits.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll almost always need some kind of wrapper function to establish a security context or identify the server that's making the request. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_sp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
The name that you give your service is entirely up to you, but you need to create a language file in (for example) lang/en_utf8/mod_forum.php to store your service name and description, for example:<br />
<br />
$string['sso_idp_name'] = 'SSO (Identity Provider)';<br />
$string['sso_idp_description'] = 'A description of the SSO IDP service that allows an admin to know if he needs it or not.';<br />
<br />
Note that your service name (in this example 'sso_idp') is suffixed with _name and _description.<br />
<br />
Turning back to the mnet_publishes function, your associative array has an 'apiversion' key, that allows you to provide more than one version of your API. This is really provided for future use, and isn't implemented in the code yet. We anticipate that eventually APIs will have to change, and this should allow newer Moodles to still be able to communicate with older Moodles. While this is unavoidable, it's something that we want to put of for as long as possible.<br />
<br />
Finally, you provide a list of method or function names that constitute the service. When an admin enables this service for a host, he's really permitting the host to remotely call the methods or functions that you list here.<br />
<br />
Calling a function remotely will require your XML-RPC client to pass something like this to the Moodle XML-RPC server as the function name:<br />
"mod/forum/rpclib.php/somefunction"<br />
<br />
==Other Implementations==<br />
XML-RPC won't work for everyone. If you're planning a REST or SOAP service, please consider putting your work into mnet/soap or mnet/rest, so that it's alongside mnet/xmlrpc. The work we've done in the mnet directory might be useful to you as well, so rather than re-invent the wheel, have a look at our code to see if it meets any of your needs.<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25539Web services API2007-08-02T00:07:04Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system/listMethods<br />
* system/methodSignature<br />
* system/methodHelp<br />
* system/listServices<br />
Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system/keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection recognise your edits.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll almost always need some kind of wrapper function to establish a security context or identify the server that's making the request. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_sp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
The name that you give your service is entirely up to you, but you need to create a language file in (for example) lang/en_utf8/mod_forum.php to store your service name and description, for example:<br />
<br />
$string['sso_idp_name'] = 'SSO (Identity Provider)';<br />
$string['sso_idp_description'] = 'A description of the SSO IDP service that allows an admin to know if he needs it or not.';<br />
<br />
Note that your service name (in this example 'sso_idp') is suffixed with _name and _description.<br />
<br />
Turning back to the mnet_publishes function, your associative array has an 'apiversion' key, that allows you to provide more than one version of your API. This is really provided for future use, and isn't implemented in the code yet. We anticipate that eventually APIs will have to change, and this should allow newer Moodles to still be able to communicate with older Moodles. While this is unavoidable, it's something that we want to put of for as long as possible.<br />
<br />
Finally, you provide a list of method or function names that constitute the service. When an admin enables this service for a host, he's really permitting the host to remotely call the methods or functions that you list here.<br />
<br />
Calling a function remotely will require your XML-RPC client to pass something like this to the Moodle XML-RPC server as the function name:<br />
"mod/forum/rpclib.php/somefunction"<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25538Web services API2007-08-01T23:49:03Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection recognise your edits.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll almost always need some kind of wrapper function to establish a security context or identify the server that's making the request. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_sp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
The name that you give your service is entirely up to you, but you need to create a language file in (for example) lang/en_utf8/mod_forum.php to store your service name and description, for example:<br />
<br />
$string['sso_idp_name'] = 'SSO (Identity Provider)';<br />
$string['sso_idp_description'] = 'A description of the SSO IDP service that allows an admin to know if he needs it or not.';<br />
<br />
Note that your service name (in this example 'sso_idp') is suffixed with _name and _description.<br />
<br />
Turning back to the mnet_publishes function, your associative array has an 'apiversion' key, that allows you to provide more than one version of your API. This is really provided for future use, and isn't implemented in the code yet. We anticipate that eventually APIs will have to change, and this should allow newer Moodles to still be able to communicate with older Moodles. While this is unavoidable, it's something that we want to put of for as long as possible.<br />
<br />
Finally, you provide a list of method or function names that constitute the service. When an admin enables this service for a host, he's really permitting the host to remotely call the methods or functions that you list here.<br />
<br />
Calling a function remotely will require your XML-RPC client to pass something like this to the Moodle XML-RPC server as the function name:<br />
"mod/forum/rpclib.php/somefunction"<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25537Web services API2007-08-01T23:44:33Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll almost always need some kind of wrapper function to establish a security context or identify the server that's making the request. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_sp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
The name that you give your service is entirely up to you, but you need to create a language file in (for example) lang/en_utf8/mod_forum.php to store your service name and description, for example:<br />
<br />
$string['sso_idp_name'] = 'SSO (Identity Provider)';<br />
$string['sso_idp_description'] = 'A description of the SSO IDP service that allows an admin to know if he needs it or not.';<br />
<br />
Note that your service name (in this example 'sso_idp') is suffixed with _name and _description.<br />
<br />
Turning back to the mnet_publishes function, your associative array has an 'apiversion' key, that allows you to provide more than one version of your API. This is really provided for future use, and isn't implemented in the code yet. We anticipate that eventually APIs will have to change, and this should allow newer Moodles to still be able to communicate with older Moodles. While this is unavoidable, it's something that we want to put of for as long as possible.<br />
<br />
Finally, you provide a list of method or function names that constitute the service. When an admin enables this service for a host, he's really permitting the host to remotely call the methods or functions that you list here.<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25536Web services API2007-08-01T23:27:55Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll normally need some kind of wrapper function to establish a security context or identify the server that's making the request or what have you. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_idp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
The name that you give your service is fairly arbitrary, but it will be presented to the system administrator to allow him to enable or disable your service for each host that he peers with, so it should be adequately descriptive to allow him to do this with confidence.<br />
<br />
Generally, you want to get your API right first time and then never change it, but if you find that you need to revise it in future, you can enable more than one version of the same service for XML-RPC.<br />
<br />
Finally, you provide a list of methods that constitute the service. When an admin enables this service for a host, he's permitting the host to remotely call the methods or functions that you list here.<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25535Web services API2007-08-01T23:27:25Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an array of associative arrays with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
return array($yummy_beer);<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll normally need some kind of wrapper function to establish a security context or identify the server that's making the request or what have you. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_idp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
The name that you give your service is fairly arbitrary, but it will be presented to the system administrator to allow him to enable or disable your service for each host that he peers with, so it should be adequately descriptive to allow him to do this with confidence.<br />
<br />
Generally, you want to get your API right first time and then never change it, but if you find that you need to revise it in future, you can enable more than one version of the same service for XML-RPC.<br />
<br />
Finally, you provide a list of methods that constitute the service. When an admin enables this service for a host, he's permitting the host to remotely call the methods or functions that you list here.<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25534Web services API2007-08-01T23:26:03Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an associative array with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
==Functions in Modules==<br />
The mechanics of XML-RPC are such that there are few functions that it would be useful to call directly from a remote server; you'll normally need some kind of wrapper function to establish a security context or identify the server that's making the request or what have you. Partly for this reason, and partly so that it would be really obvious which functions are available to remote servers (i.e. really difficult for someone to call some arbitrary function in Moodle), we mandated that all XML-RPC-callable functions should be implemented in a special file called rpclib.php, so if you want to call a function in mod/forum/lib.php, you'll need to create a file called mod/forum/rpclib.php, and implement a wrapper function in that file that calls the function in mod/forum/lib.php.<br />
<br />
For rpclib.php files, it is still also necessary to create an mnet_publishes function. This function must return an array in the same format as the one detailed above for auth and enrol plugins. Let's look at that in a little more detail by reviewing the method from the auth_plugin_mnet class.<br />
<br />
For the benefit of administrators, your functions must be grouped into "Services". Some of the services that we've already implemented include sso_idp; the 'Single-Sign-On Identity Provider' service, and sso_idp; the 'Single-Sign-On Service Provider' service. You can see that the mnet_publishes method for that plugin returns an array with two elements. These elements provide information on the sso_idp and sso_sp services.<br />
<br />
/**<br />
* Provides the allowed RPC services from this class as an array.<br />
* @return array Allowed RPC services.<br />
*/<br />
function mnet_publishes() {<br />
<br />
$sso_idp = array();<br />
$sso_idp['name'] = 'sso_idp'; // Name & Description go in lang file<br />
$sso_idp['apiversion'] = 1;<br />
$sso_idp['methods'] = array('user_authorise','keepalive_server', 'kill_children',<br />
'refresh_log', 'fetch_user_image', 'fetch_theme_info',<br />
'update_enrolments');<br />
<br />
$sso_sp = array();<br />
$sso_sp['name'] = 'sso_sp'; // Name & Description go in lang file<br />
$sso_sp['apiversion'] = 1;<br />
$sso_sp['methods'] = array('keepalive_client','kill_child');<br />
<br />
return array($sso_idp, $sso_sp);<br />
}<br />
<br />
The name that you give your service is fairly arbitrary, but it will be presented to the system administrator to allow him to enable or disable your service for each host that he peers with, so it should be adequately descriptive to allow him to do this with confidence.<br />
<br />
Generally, you want to get your API right first time and then never change it, but if you find that you need to revise it in future, you can enable more than one version of the same service for XML-RPC.<br />
<br />
Finally, you provide a list of methods that constitute the service. When an admin enables this service for a host, he's permitting the host to remotely call the methods or functions that you list here.<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25533Web services API2007-08-01T22:25:36Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an associative array with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
When you're writing your method, it's good practice to add a docblock with @param and @return values, because Moodle will read that information and provide it on to remote servers who call the introspection methods (e.g. system.methodSignature). This information is updated every time you hit /admin/index.php, so if you update the docblock for your function, you need to visit that page to have Moodle's introspection.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25532Web services API2007-08-01T22:21:47Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an associative array with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"auth/bribeme/auth.php/buymebeer"<br />
<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25531Web services API2007-08-01T22:18:13Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an associative array with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
So - once you've implemented your method, you're ready to call it from your application. Your XML-RPC client needs to pass a function name to Moodle's XML-RPC server, that allows the server to identify the file and function to execute. The name you pass is a concatenation of the path to the file, and the name of your function, e.g.<br />
<br />
"/auth/bribeme/auth.php/buymebeer"<br />
<br />
<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25485Web services API2007-07-31T07:47:00Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
I recommend that you enter something like this (assuming your application's IP address is 192.168.0.7):<br />
192.168.0.7/32<br />
<br />
That's all you need. Moodle knows your server is friendly, and will XML-RPC with it, without requiring it to encrypt or sign anything.<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==Methods of auth and enrol objects==<br />
Let's say you have an enrolment class called 'enrol_plugin_bribeme' with the method "buy_me_beer" and you want to be able to call it via XML-RPC. First, your class' constructor must not require arguments. The despatcher should be able to just ask for your enrolment object and get it... end of story.<br />
<br />
Second - enrol_plugin_bribeme must have a method called mnet_publishes which returns information about the "buy_me_beer" method. The method should return an associative array with the following structure:<br />
$yummy_beer = array();<br />
$yummy_beer['name'] = 'yummy_beer'; // Name ('Yummy Beer!') goes in lang file<br />
$yummy_beer['apiversion'] = 1;<br />
$yummy_beer['methods'] = array('buy_me_beer');<br />
<br />
The $yummy_beer['methods'] array can contain any number of method names. The $yummy_beer['name'] element is the name of this service, and this will appear in the admin interface to allow the service to be enabled and disabled for different hosts. You enter an identifier here, and the actual name goes in the appropriate lang file - in this case lang/en_utf8/enrol_bribeme.php.<br />
<br />
Just implement your method, and you're done.<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25484Web services API2007-07-31T07:29:43Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code, so I'm not telling you where it is.<br />
<br />
==Tell us!==<br />
Oh alright then. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'. Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first, however, if you do enable this and your site does got pwned please tell me so I can laugh and high five my co-workers.<br />
<br />
==So - back to those four categories of function we were talking about==<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be friendly to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25483Web services API2007-07-31T07:21:59Z<p>Donalm: </p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
Plaintext networking is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==A word on Encryption==<br />
There's really no voodoo going on in the Moodle encryption and signing process. We've tried to stick to the W3C's XML-ENC and XML-DSIG standards, and because our implementation of them is fairly simple and naive, getting your application to mimic that behaviour's is not (as we say) rocket surgery. The Mahara implementation of XML-ENC/XML-DSIG uses some PHP5 features that make things even easier, so that might be a useful starting point for adventurous hackers.<br />
<br />
==But if I'm not using Encryption?==<br />
Then you need to tell Moodle to privilege the machine on which your application is running, and allow it to use the XML-RPC service without having to sign or encrypt its messages. You can do this at /admin/mnet/trustedhosts.php, which you can browse to in the admin panel at<br />
Networking:XML-RPC hosts<br />
<br />
==What can Moodle's XML-RPC do?==<br />
By default, we've strictly limited the functions that can be remotely called. These fall into four categories:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
==But what if I have a death wish or something?==<br />
Don't worry - we've thought of you too. If you want to do something that's not in that list, there is a special 'shoot-yourself-in-the-foot' switch that you can enable by tweaking a field in your database. This switch - if enabled - would allow the remote application to do ANYTHING to your Moodle that has a corresponding function anywhere in the code. In your config table, the row with the 'name' mnet_dispatcher_mode, should have a 'value' of 'promiscuous'.<br />
<br />
Please don't do that. There are other ways to enable whatever it is you want to enable, so please exhaust those first.<br />
<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be useful to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25482Web services API2007-07-31T07:01:50Z<p>Donalm: /* XML-RPC background */</p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
This is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
By default, there are four kinds of function that might be called remotely:<br />
* special 'system' functions<br />
* methods of an authorisation object<br />
* methods of an enrolment object<br />
* functions in a module<br />
<br />
The system functions return information about the services and methods that your API is making available to remote servers. These functions are:<br />
* system.listMethods<br />
* system.methodSignature<br />
* system.methodHelp<br />
* system.listServices<br />
The dot-notation is not an XML-RPC standard, but it does seem to be widely deployed, so we figured it would be useful to implement that. You can call all of these methods with a slash (like system/listMethods) if that's important to you. Missing from this list is a non-standard method, that we implemented to help with key-exchange and key-rotation:<br />
* system.keyswap<br />
This method returns the public key that your Moodle and Mahara peers will use for message encryption and signing. It is always possible to call this method from any host without signing or encryption, otherwise Moodles would never be able to exchange keys, and for that reason, it might be really useful to use as a test function. If you get a result back from this function, you have a foot in the door to setting up plaintext XML-RPC between your application and Moodle.<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=25481Web services API2007-07-31T06:24:03Z<p>Donalm: /* XML-RPC background */</p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, bypassing Moodle Network's encryption or signed-message features.<br />
<br />
This is only likely to be useful if you have another application which:<br />
* is not a Moodle<br />
* is completely under your control (for security reasons)<br />
<br />
==The server script==<br />
* allow trusted sites to access web services by configuring '''admin/mnet/trustedhosts.php'''<br />
* start by pointing your browser to '''mnet/xmlrpc/server.php''' - this should show an XML error message<br />
* use POST data in this format:<br />
// $method is something like: "mod/forum/lib/forum_add_instance"<br />
// $params is an array of parameters. A parameter might itself be an array.<br />
// use only Whitelist characters that are permitted in a method name<br />
// The method name must not begin with a / - avoid absolute paths<br />
// A dot character . is only allowed in the filename, i.e. something.php<br />
* use '''mnet/xmlrpc/client.php''' to make remote xmlrpc calls<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=24820Web services API2007-07-05T06:06:01Z<p>Donalm: /* XML-RPC background */</p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network [https://docs.moodle.org/en/Moodle_Network] features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, with Moodle Network's encryption or signed-message features.<br />
<br />
==The server script==<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=Web_services_API&diff=24819Web services API2007-07-05T06:01:15Z<p>Donalm: /* XML-RPC background */</p>
<hr />
<div>== Overview ==<br />
<br />
<br />
The Web Services API provides Moodle with a web service interface to allow exchange of data and information with other systems.<br />
<br />
For example,<br />
# Manage user data - send and retrieve the information,<br />
# Manage course enrolments - add/remove teachers and students,<br />
# Course management - create new courses based on templates,<br />
# Gradebook info - extract grades information from Moodle.<br />
<br />
==XML-RPC background==<br />
The XML-RPC service allows other servers to contact your Moodle server and request that it call a function. The Moodle server might do something, like create a user, or it might fetch some data and serve it back to your host.<br />
<br />
To communicate like this with another Moodle host, you'd normally use the Moodle Network features, but it's also possible for other kinds of program to contact your Moodle, using plain-old-XML-RPC, with Moodle Network's encryption or signed-message features.<br />
<br />
==The server script==<br />
<br />
==Things you can do==<br />
<br />
==See also==<br />
<br />
* Using Moodle [http://moodle.org/mod/forum/view.php?f=965 Web Services forum] <br />
<br />
[[Category:Developer|Web services API]]<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=MNet&diff=19267MNet2007-01-10T20:59:46Z<p>Donalm: /* Security */</p>
<hr />
<div>{{Moodle 1.8}}<br />
<p class="note">''Draft -- for 1.8 functionality'' --[[User:Martin Langhoff|Martin Langhoff]] 22:44, 26 December 2006 (CST) </p><br />
<br />
=Overview=<br />
Moodle Network is a new feature that is set to be a part of the 1.8 release of Moodle. 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.<br />
<br />
The initial release of Moodle Network is bundled with a new Authentication Plugin, which makes single-sign-on between Moodles possible. A user with the username <em>jody</em> 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.<br />
<br />
=Security=<br />
The Moodle network 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).<br />
<br />
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.<br />
<br />
Refs:<br /><br />
[http://www.w3.org/TR/xmldsig-core/ XML Digital Signatures]<br /><br />
[http://www.w3.org/TR/xmlenc-core/ XML Encryption]<br />
<br />
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.<br />
<br />
=Peer to Peer Network=<br />
<br />
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. <br />
<br />
==Setup==<br />
<br />
The instructions will cover 2 Moodle installations: MoodleA and MoodleB. Both are installed correctly and have never had a Moodle Network configuration.<br />
<br />
# Get them to talk to eachother<br />
## Ensure Admin / Server / Environment indicates you have curl installed<br />
## 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! <br />
## On both, go to Admin / Network / Settings and turn Networking ON.<br />
## On MoodleA go to Admin / Network / Peers - put the URL of MoodleB under "Add New Host" and click Add.<br />
## Do the equivalent on MoodleB.<br />
# Get user roaming going<br />
## On both, go to Admin / Users / Authentication and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable SSO-IDP publish and subscribe, and SSO-SP publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## On both, got 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.<br />
## On both, go to the homepage, and add the 'Network Servers' block.<br />
## 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. <br />
# Get remote enrolments going -- this is optional. It allows administrator of MoodleB can enrol users that are "native" to MoodleB in courses in MoodleA, and viceversa.<br />
## On both, go to Admin / Courses / Enrolment 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.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable Enrolment publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## To use, in MoodleA go to Admin / Courses / Enrolment / Moodle Network -> Edit / Manage Network Enrolments and you will see MoodleB listed. Click on MoodleB and you will see a list of your users, and the courses that MoodleB offers for remote enrolment.<br />
<br />
==Using it==<br />
<br />
=Connecting to a Community Hub=<br />
A Community Hub 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 Community Hub, assess the services it has to offer, and enable those services for your users.<br />
==Setup==<br />
# Get talking to the Hub<br />
## Ensure that the Admin / Server / Environment page indicates you have curl and openssl installed<br />
## Go to Admin / Network / Settings and turn Networking on<br />
## Go to Admin / Network / Peers and enter the URL of Community Hub under "Add New Host". Click <em>Add</em><br />
## The host details for the Community Hub should appear with the Site Name field already populated. Click <em>Save changes</em><br />
## The details will be written to your database and two new tabs will appear in this window: 'Services' and 'Logs'. Click <em>Services</em><br />
##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<br />
==Using it==<br />
If the Community Hub has already enabled a service for you, there will be a tick alongside the appropriate checkbox, for example: if the Hub is <em>publishing</em> Moodle Networked Enrolment, then a tick will appear alongside the <em>subscribe</em> checkbox for this service. Note that in order to enable some functionality, prominently <em>single-sign-on</em>, you may have to <em>publish</em> a service, e.g. the <em>Identity Provider</em> service. The Community Hub will access this service on your Moodle, asking it to authenticate your users.<br />
# Enable Roaming<br />
## Subscribe to <em>SSO (Service Provider)</em> by checking the box<br />
## Publish <em>SSO (Identity Provider)</em> by checking the box<br />
## Click <em>Save changes</em><br />
## Go to Admin / Users / Permissions / Define Roles, and grant the capability <em>Roam to a remote Moodle moodle/site:mnetlogintoremote</em> to an appropriate role<br />
## Go to Admin / Users / Authentication and enable the <em>Moodle Network authentication</em> plugin<br />
## Go to your homepage, turn on editing, and add the 'Network Servers' block<br />
## Using a different web-browser, log on as a non-admin user who inhabits the role you granted the roaming capability to<br />
## Note that the Community Hub is listed in the Network Servers block on the homepage. Click on the link to that server<br />
## Some of your user details will be transferred to the Community Hub server, and a browsing session will be started for you as if you had logged on there directly<br />
# Enable Networked Enrolment<br />
## Return to the web browser you've been using as the site administrator<br />
## Go to Admin / Network / Peers and click on the entry for the Community Hub.<br />
## Click on the Services tab<br />
## Subscribe to <em>Moodle Networked Enrolment</em><br />
## Go to Admin / Courses / Enrolment and enable the <em>Moodle Network enrolment</em> plugin. Click <em>Save changes</em><br />
## Click on <em>edit</em> to view the details for networked enrolments.<br />
## Click on <em>Manage Moodle Network Enrolments</em> to see a list of Moodle servers that offer this service to you<br />
## Click on a server name to view a list of courses that the server offers to your users<br />
## Click on a course name, to view a list users that you can enrol in this course<br />
## Enrol users<br />
## Profit!<br />
<br />
=Running a community Hub=<br />
A Community 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.<br />
<br />
A Community Hub is different. As soon as you add an entry for a Community Hub to your system, the Community 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.<br />
This section will guide you to set up a community hub, and select services to offer to all comers.<br />
==Setup==<br />
# Enable Networking<br />
## Ensure that the Admin / Server / Environment page indicates you have curl and openssl installed<br />
## Go to Admin / Network / Settings and turn Networking on <br />
## Go to Admin / Network / Peers and tick the checkbox for <em>Register all hosts</em>. Click on <em>Save Changes</em><br />
## On the same page, the first entry in your list of hosts should be <em>All hosts</em>. Click this link<br />
## Click on <em>Services</em> and enable any services you want to offer to all comers<br />
<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=MNet&diff=19265MNet2007-01-10T20:44:28Z<p>Donalm: /* Overview */</p>
<hr />
<div>{{Moodle 1.8}}<br />
<p class="note">''Draft -- for 1.8 functionality'' --[[User:Martin Langhoff|Martin Langhoff]] 22:44, 26 December 2006 (CST) </p><br />
<br />
=Overview=<br />
Moodle Network is a new feature that is set to be a part of the 1.8 release of Moodle. 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.<br />
<br />
The initial release of Moodle Network is bundled with a new Authentication Plugin, which makes single-sign-on between Moodles possible. A user with the username <em>jody</em> 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.<br />
<br />
=Security=<br />
<br />
<br />
=Peer to Peer Network=<br />
<br />
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. <br />
<br />
==Setup==<br />
<br />
The instructions will cover 2 Moodle installations: MoodleA and MoodleB. Both are installed correctly and have never had a Moodle Network configuration.<br />
<br />
# Get them to talk to eachother<br />
## Ensure Admin / Server / Environment indicates you have curl installed<br />
## 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! <br />
## On both, go to Admin / Network / Settings and turn Networking ON.<br />
## On MoodleA go to Admin / Network / Peers - put the URL of MoodleB under "Add New Host" and click Add.<br />
## Do the equivalent on MoodleB.<br />
# Get user roaming going<br />
## On both, go to Admin / Users / Authentication and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable SSO-IDP publish and subscribe, and SSO-SP publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## On both, got 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.<br />
## On both, go to the homepage, and add the 'Network Servers' block.<br />
## 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. <br />
# Get remote enrolments going -- this is optional. It allows administrator of MoodleB can enrol users that are "native" to MoodleB in courses in MoodleA, and viceversa.<br />
## On both, go to Admin / Courses / Enrolment 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.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable Enrolment publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## To use, in MoodleA go to Admin / Courses / Enrolment / Moodle Network -> Edit / Manage Network Enrolments and you will see MoodleB listed. Click on MoodleB and you will see a list of your users, and the courses that MoodleB offers for remote enrolment.<br />
<br />
==Using it==<br />
<br />
=Connecting to a Community Hub=<br />
A Community Hub 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 Community Hub, assess the services it has to offer, and enable those services for your users.<br />
==Setup==<br />
# Get talking to the Hub<br />
## Ensure that the Admin / Server / Environment page indicates you have curl and openssl installed<br />
## Go to Admin / Network / Settings and turn Networking on<br />
## Go to Admin / Network / Peers and enter the URL of Community Hub under "Add New Host". Click <em>Add</em><br />
## The host details for the Community Hub should appear with the Site Name field already populated. Click <em>Save changes</em><br />
## The details will be written to your database and two new tabs will appear in this window: 'Services' and 'Logs'. Click <em>Services</em><br />
##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<br />
==Using it==<br />
If the Community Hub has already enabled a service for you, there will be a tick alongside the appropriate checkbox, for example: if the Hub is <em>publishing</em> Moodle Networked Enrolment, then a tick will appear alongside the <em>subscribe</em> checkbox for this service. Note that in order to enable some functionality, prominently <em>single-sign-on</em>, you may have to <em>publish</em> a service, e.g. the <em>Identity Provider</em> service. The Community Hub will access this service on your Moodle, asking it to authenticate your users.<br />
# Enable Roaming<br />
## Subscribe to <em>SSO (Service Provider)</em> by checking the box<br />
## Publish <em>SSO (Identity Provider)</em> by checking the box<br />
## Click <em>Save changes</em><br />
## Go to Admin / Users / Permissions / Define Roles, and grant the capability <em>Roam to a remote Moodle moodle/site:mnetlogintoremote</em> to an appropriate role<br />
## Go to Admin / Users / Authentication and enable the <em>Moodle Network authentication</em> plugin<br />
## Go to your homepage, turn on editing, and add the 'Network Servers' block<br />
## Using a different web-browser, log on as a non-admin user who inhabits the role you granted the roaming capability to<br />
## Note that the Community Hub is listed in the Network Servers block on the homepage. Click on the link to that server<br />
## Some of your user details will be transferred to the Community Hub server, and a browsing session will be started for you as if you had logged on there directly<br />
# Enable Networked Enrolment<br />
## Return to the web browser you've been using as the site administrator<br />
## Go to Admin / Network / Peers and click on the entry for the Community Hub.<br />
## Click on the Services tab<br />
## Subscribe to <em>Moodle Networked Enrolment</em><br />
## Go to Admin / Courses / Enrolment and enable the <em>Moodle Network enrolment</em> plugin. Click <em>Save changes</em><br />
## Click on <em>edit</em> to view the details for networked enrolments.<br />
## Click on <em>Manage Moodle Network Enrolments</em> to see a list of Moodle servers that offer this service to you<br />
## Click on a server name to view a list of courses that the server offers to your users<br />
## Click on a course name, to view a list users that you can enrol in this course<br />
## Enrol users<br />
## Profit!<br />
<br />
=Running a community Hub=<br />
A Community 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.<br />
<br />
A Community Hub is different. As soon as you add an entry for a Community Hub to your system, the Community 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.<br />
This section will guide you to set up a community hub, and select services to offer to all comers.<br />
==Setup==<br />
# Enable Networking<br />
## Ensure that the Admin / Server / Environment page indicates you have curl and openssl installed<br />
## Go to Admin / Network / Settings and turn Networking on <br />
## Go to Admin / Network / Peers and tick the checkbox for <em>Register all hosts</em>. Click on <em>Save Changes</em><br />
## On the same page, the first entry in your list of hosts should be <em>All hosts</em>. Click this link<br />
## Click on <em>Services</em> and enable any services you want to offer to all comers<br />
<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=MNet&diff=19242MNet2007-01-10T06:22:49Z<p>Donalm: /* Overview */</p>
<hr />
<div>{{Moodle 1.8}}<br />
<p class="note">''Draft -- for 1.8 functionality'' --[[User:Martin Langhoff|Martin Langhoff]] 22:44, 26 December 2006 (CST) </p><br />
<br />
=Overview=<br />
Moodle Network is a new feature that is set to be a part of the 1.8 release of Moodle. 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.<br />
<br />
The initial release of Moodle Network is bundled with a new Authentication Plugin, which makes single-sign-on between Moodles possible. A user with the username <em>jody</em> 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.<br />
<br />
In earlier releases of Moodle, no two users could have the same username. From Moodle 1.8 onwards, a username will be unique <em>per server</em> so a user who authenticates elsewhere, and then roams to your site via single-sign-on, could have the same username as a user on your site.<br />
<br />
=Security=<br />
<br />
<br />
=Peer to Peer Network=<br />
<br />
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. <br />
<br />
==Setup==<br />
<br />
The instructions will cover 2 Moodle installations: MoodleA and MoodleB. Both are installed correctly and have never had a Moodle Network configuration.<br />
<br />
# Get them to talk to eachother<br />
## Ensure Admin / Server / Environment indicates you have curl installed<br />
## 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! <br />
## On both, go to Admin / Network / Settings and turn Networking ON.<br />
## On MoodleA go to Admin / Network / Peers - put the URL of MoodleB under "Add New Host" and click Add.<br />
## Do the equivalent on MoodleB.<br />
# Get user roaming going<br />
## On both, go to Admin / Users / Authentication and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable SSO-IDP publish and subscribe, and SSO-SP publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## On both, got 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.<br />
## On both, go to the homepage, and add the 'Network Servers' block.<br />
## 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. <br />
# Get remote enrolments going -- this is optional. It allows administrator of MoodleB can enrol users that are "native" to MoodleB in courses in MoodleA, and viceversa.<br />
## On both, go to Admin / Courses / Enrolment 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.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable Enrolment publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## To use, in MoodleA go to Admin / Courses / Enrolment / Moodle Network -> Edit / Manage Network Enrolments and you will see MoodleB listed. Click on MoodleB and you will see a list of your users, and the courses that MoodleB offers for remote enrolment.<br />
<br />
==Using it==<br />
<br />
=Connecting to a Community Hub=<br />
A Community Hub 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 Community Hub, assess the services it has to offer, and enable those services for your users.<br />
==Setup==<br />
# Get talking to the Hub<br />
## Ensure that the Admin / Server / Environment page indicates you have curl and openssl installed<br />
## Go to Admin / Network / Settings and turn Networking on<br />
## Go to Admin / Network / Peers and enter the URL of Community Hub under "Add New Host". Click <em>Add</em><br />
## The host details for the Community Hub should appear with the Site Name field already populated. Click <em>Save changes</em><br />
## The details will be written to your database and two new tabs will appear in this window: 'Services' and 'Logs'. Click <em>Services</em><br />
##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<br />
==Using it==<br />
If the Community Hub has already enabled a service for you, there will be a tick alongside the appropriate checkbox, for example: if the Hub is <em>publishing</em> Moodle Networked Enrolment, then a tick will appear alongside the <em>subscribe</em> checkbox for this service. Note that in order to enable some functionality, prominently <em>single-sign-on</em>, you may have to <em>publish</em> a service, e.g. the <em>Identity Provider</em> service. The Community Hub will access this service on your Moodle, asking it to authenticate your users.<br />
# Enable Roaming<br />
## Subscribe to <em>SSO (Service Provider)</em> by checking the box<br />
## Publish <em>SSO (Identity Provider)</em> by checking the box<br />
## Click <em>Save changes</em><br />
## Go to Admin / Users / Permissions / Define Roles, and grant the capability <em>Roam to a remote Moodle moodle/site:mnetlogintoremote</em> to an appropriate role<br />
## Go to Admin / Users / Authentication and enable the <em>Moodle Network authentication</em> plugin<br />
## Go to your homepage, turn on editing, and add the 'Network Servers' block<br />
## Using a different web-browser, log on as a non-admin user who inhabits the role you granted the roaming capability to<br />
## Note that the Community Hub is listed in the Network Servers block on the homepage. Click on the link to that server<br />
## Some of your user details will be transferred to the Community Hub server, and a browsing session will be started for you as if you had logged on there directly<br />
# Enable Networked Enrolment<br />
## Return to the web browser you've been using as the site administrator<br />
## Go to Admin / Network / Peers and click on the entry for the Community Hub.<br />
## Click on the Services tab<br />
## Subscribe to <em>Moodle Networked Enrolment</em><br />
## Go to Admin / Courses / Enrolment and enable the <em>Moodle Network enrolment</em> plugin. Click <em>Save changes</em><br />
## Click on <em>edit</em> to view the details for networked enrolments.<br />
## Click on <em>Manage Moodle Network Enrolments</em> to see a list of Moodle servers that offer this service to you<br />
## Click on a server name to view a list of courses that the server offers to your users<br />
## Click on a course name, to view a list users that you can enrol in this course<br />
## Enrol users<br />
## Profit!<br />
<br />
=Running a community Hub=<br />
A Community 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.<br />
<br />
A Community Hub is different. As soon as you add an entry for a Community Hub to your system, the Community 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.<br />
This section will guide you to set up a community hub, and select services to offer to all comers.<br />
==Setup==<br />
# Enable Networking<br />
## Ensure that the Admin / Server / Environment page indicates you have curl and openssl installed<br />
## Go to Admin / Network / Settings and turn Networking on <br />
## Go to Admin / Network / Peers and tick the checkbox for <em>Register all hosts</em>. Click on <em>Save Changes</em><br />
## On the same page, the first entry in your list of hosts should be <em>All hosts</em>. Click this link<br />
## Click on <em>Services</em> and enable any services you want to offer to all comers<br />
<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=MNet&diff=19241MNet2007-01-10T05:59:40Z<p>Donalm: /* Running a community Hub */</p>
<hr />
<div>{{Moodle 1.8}}<br />
<p class="note">''Draft -- for 1.8 functionality'' --[[User:Martin Langhoff|Martin Langhoff]] 22:44, 26 December 2006 (CST) </p><br />
<br />
=Overview=<br />
<br />
=Security=<br />
<br />
<br />
=Peer to Peer Network=<br />
<br />
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. <br />
<br />
==Setup==<br />
<br />
The instructions will cover 2 Moodle installations: MoodleA and MoodleB. Both are installed correctly and have never had a Moodle Network configuration.<br />
<br />
# Get them to talk to eachother<br />
## Ensure Admin / Server / Environment indicates you have curl installed<br />
## 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! <br />
## On both, go to Admin / Network / Settings and turn Networking ON.<br />
## On MoodleA go to Admin / Network / Peers - put the URL of MoodleB under "Add New Host" and click Add.<br />
## Do the equivalent on MoodleB.<br />
# Get user roaming going<br />
## On both, go to Admin / Users / Authentication and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable SSO-IDP publish and subscribe, and SSO-SP publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## On both, got 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.<br />
## On both, go to the homepage, and add the 'Network Servers' block.<br />
## 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. <br />
# Get remote enrolments going -- this is optional. It allows administrator of MoodleB can enrol users that are "native" to MoodleB in courses in MoodleA, and viceversa.<br />
## On both, go to Admin / Courses / Enrolment 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.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable Enrolment publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## To use, in MoodleA go to Admin / Courses / Enrolment / Moodle Network -> Edit / Manage Network Enrolments and you will see MoodleB listed. Click on MoodleB and you will see a list of your users, and the courses that MoodleB offers for remote enrolment.<br />
<br />
==Using it==<br />
<br />
=Connecting to a Community Hub=<br />
A Community Hub 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 Community Hub, assess the services it has to offer, and enable those services for your users.<br />
==Setup==<br />
# Get talking to the Hub<br />
## Ensure that the Admin / Server / Environment page indicates you have curl and openssl installed<br />
## Go to Admin / Network / Settings and turn Networking on<br />
## Go to Admin / Network / Peers and enter the URL of Community Hub under "Add New Host". Click <em>Add</em><br />
## The host details for the Community Hub should appear with the Site Name field already populated. Click <em>Save changes</em><br />
## The details will be written to your database and two new tabs will appear in this window: 'Services' and 'Logs'. Click <em>Services</em><br />
##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<br />
==Using it==<br />
If the Community Hub has already enabled a service for you, there will be a tick alongside the appropriate checkbox, for example: if the Hub is <em>publishing</em> Moodle Networked Enrolment, then a tick will appear alongside the <em>subscribe</em> checkbox for this service. Note that in order to enable some functionality, prominently <em>single-sign-on</em>, you may have to <em>publish</em> a service, e.g. the <em>Identity Provider</em> service. The Community Hub will access this service on your Moodle, asking it to authenticate your users.<br />
# Enable Roaming<br />
## Subscribe to <em>SSO (Service Provider)</em> by checking the box<br />
## Publish <em>SSO (Identity Provider)</em> by checking the box<br />
## Click <em>Save changes</em><br />
## Go to Admin / Users / Permissions / Define Roles, and grant the capability <em>Roam to a remote Moodle moodle/site:mnetlogintoremote</em> to an appropriate role<br />
## Go to Admin / Users / Authentication and enable the <em>Moodle Network authentication</em> plugin<br />
## Go to your homepage, turn on editing, and add the 'Network Servers' block<br />
## Using a different web-browser, log on as a non-admin user who inhabits the role you granted the roaming capability to<br />
## Note that the Community Hub is listed in the Network Servers block on the homepage. Click on the link to that server<br />
## Some of your user details will be transferred to the Community Hub server, and a browsing session will be started for you as if you had logged on there directly<br />
# Enable Networked Enrolment<br />
## Return to the web browser you've been using as the site administrator<br />
## Go to Admin / Network / Peers and click on the entry for the Community Hub.<br />
## Click on the Services tab<br />
## Subscribe to <em>Moodle Networked Enrolment</em><br />
## Go to Admin / Courses / Enrolment and enable the <em>Moodle Network enrolment</em> plugin. Click <em>Save changes</em><br />
## Click on <em>edit</em> to view the details for networked enrolments.<br />
## Click on <em>Manage Moodle Network Enrolments</em> to see a list of Moodle servers that offer this service to you<br />
## Click on a server name to view a list of courses that the server offers to your users<br />
## Click on a course name, to view a list users that you can enrol in this course<br />
## Enrol users<br />
## Profit!<br />
<br />
=Running a community Hub=<br />
A Community 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.<br />
<br />
A Community Hub is different. As soon as you add an entry for a Community Hub to your system, the Community 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.<br />
This section will guide you to set up a community hub, and select services to offer to all comers.<br />
==Setup==<br />
# Enable Networking<br />
## Ensure that the Admin / Server / Environment page indicates you have curl and openssl installed<br />
## Go to Admin / Network / Settings and turn Networking on <br />
## Go to Admin / Network / Peers and tick the checkbox for <em>Register all hosts</em>. Click on <em>Save Changes</em><br />
## On the same page, the first entry in your list of hosts should be <em>All hosts</em>. Click this link<br />
## Click on <em>Services</em> and enable any services you want to offer to all comers<br />
<br />
[[Category:Administrator]]</div>Donalmhttps://docs.moodle.org/4x/sv/index.php?title=MNet&diff=19240MNet2007-01-10T05:44:05Z<p>Donalm: /* Connecting to a Community Hub */</p>
<hr />
<div>{{Moodle 1.8}}<br />
<p class="note">''Draft -- for 1.8 functionality'' --[[User:Martin Langhoff|Martin Langhoff]] 22:44, 26 December 2006 (CST) </p><br />
<br />
=Overview=<br />
<br />
=Security=<br />
<br />
<br />
=Peer to Peer Network=<br />
<br />
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. <br />
<br />
==Setup==<br />
<br />
The instructions will cover 2 Moodle installations: MoodleA and MoodleB. Both are installed correctly and have never had a Moodle Network configuration.<br />
<br />
# Get them to talk to eachother<br />
## Ensure Admin / Server / Environment indicates you have curl installed<br />
## 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! <br />
## On both, go to Admin / Network / Settings and turn Networking ON.<br />
## On MoodleA go to Admin / Network / Peers - put the URL of MoodleB under "Add New Host" and click Add.<br />
## Do the equivalent on MoodleB.<br />
# Get user roaming going<br />
## On both, go to Admin / Users / Authentication and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable SSO-IDP publish and subscribe, and SSO-SP publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## On both, got 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.<br />
## On both, go to the homepage, and add the 'Network Servers' block.<br />
## 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. <br />
# Get remote enrolments going -- this is optional. It allows administrator of MoodleB can enrol users that are "native" to MoodleB in courses in MoodleA, and viceversa.<br />
## On both, go to Admin / Courses / Enrolment 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.<br />
## On MoodleA go to Admin / Network / Peers, click on 'MoodleB', and click on 'Services'. Enable Enrolment publish and subscribe.<br />
## Do the equivalent on MoodleB.<br />
## To use, in MoodleA go to Admin / Courses / Enrolment / Moodle Network -> Edit / Manage Network Enrolments and you will see MoodleB listed. Click on MoodleB and you will see a list of your users, and the courses that MoodleB offers for remote enrolment.<br />
<br />
==Using it==<br />
<br />
=Connecting to a Community Hub=<br />
A Community Hub 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 Community Hub, assess the services it has to offer, and enable those services for your users.<br />
==Setup==<br />
# Get talking to the Hub<br />
## Ensure that the Admin / Server / Environment page indicates you have curl and openssl installed<br />
## Go to Admin / Network / Settings and turn Networking on<br />
## Go to Admin / Network / Peers and enter the URL of Community Hub under "Add New Host". Click <em>Add</em><br />
## The host details for the Community Hub should appear with the Site Name field already populated. Click <em>Save changes</em><br />
## The details will be written to your database and two new tabs will appear in this window: 'Services' and 'Logs'. Click <em>Services</em><br />
##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<br />
==Using it==<br />
If the Community Hub has already enabled a service for you, there will be a tick alongside the appropriate checkbox, for example: if the Hub is <em>publishing</em> Moodle Networked Enrolment, then a tick will appear alongside the <em>subscribe</em> checkbox for this service. Note that in order to enable some functionality, prominently <em>single-sign-on</em>, you may have to <em>publish</em> a service, e.g. the <em>Identity Provider</em> service. The Community Hub will access this service on your Moodle, asking it to authenticate your users.<br />
# Enable Roaming<br />
## Subscribe to <em>SSO (Service Provider)</em> by checking the box<br />
## Publish <em>SSO (Identity Provider)</em> by checking the box<br />
## Click <em>Save changes</em><br />
## Go to Admin / Users / Permissions / Define Roles, and grant the capability <em>Roam to a remote Moodle moodle/site:mnetlogintoremote</em> to an appropriate role<br />
## Go to Admin / Users / Authentication and enable the <em>Moodle Network authentication</em> plugin<br />
## Go to your homepage, turn on editing, and add the 'Network Servers' block<br />
## Using a different web-browser, log on as a non-admin user who inhabits the role you granted the roaming capability to<br />
## Note that the Community Hub is listed in the Network Servers block on the homepage. Click on the link to that server<br />
## Some of your user details will be transferred to the Community Hub server, and a browsing session will be started for you as if you had logged on there directly<br />
# Enable Networked Enrolment<br />
## Return to the web browser you've been using as the site administrator<br />
## Go to Admin / Network / Peers and click on the entry for the Community Hub.<br />
## Click on the Services tab<br />
## Subscribe to <em>Moodle Networked Enrolment</em><br />
## Go to Admin / Courses / Enrolment and enable the <em>Moodle Network enrolment</em> plugin. Click <em>Save changes</em><br />
## Click on <em>edit</em> to view the details for networked enrolments.<br />
## Click on <em>Manage Moodle Network Enrolments</em> to see a list of Moodle servers that offer this service to you<br />
## Click on a server name to view a list of courses that the server offers to your users<br />
## Click on a course name, to view a list users that you can enrol in this course<br />
## Enrol users<br />
## Profit!<br />
<br />
=Running a community Hub=<br />
<br />
==Setup==<br />
<br />
==Helping others use it==<br />
<br />
<br />
[[Category:Administrator]]</div>Donalm