Web Services:OK Tech Web Services

Moodle1.9

Moodle 2.0

Purpose

A major announcement of Moodle 2.0 is the Web Service Support allowing the admin to expose particular functions of Moodle for use by Administrative Systems such as HR or SIS applications or Mobile clients. All defined functions are automatically available via :

   * XML-RPC
   * AMF (Flash)
   * REST (any language)
   * SOAP (PHP only) 

This extremely elegant and promising solution will definitively make obsolete previous attempts such as the SOAP based Open Knowledge Technologies Web Services described here. However current [Moodle 2.0 implementation] suffers of two limitations :

• The current server implementation doesn't work with Java/.Net because we didn't generated a fully describe WSDL yet.

• The list of supported operations is still limited

This page was started in November 2010 to try to summarize the huge amount of information in this OK Tech Web Services forum and help developers still needing a Soap approach to continue to use this solution and eventually port their existing clients on a Moodle 2.0 server. Contributors are welcome to update this page, and especially help to document all parameters required and returned by operations.

It is obvious that new Web Service based developments should use the official Moodle 2.0 approach, thus helping the community to extend it.

History

The original Soap based Web Service for Moodle 1.7, was announced by Open Knowledge Technologies in March 2007 at the beginning of this discussion. My 'fork' was announced in May 2007. As you can see in the discussion above I took over the answers to most questions since mid 2007.

I kept the name OK Tech WS and to avoid confusion I added some 'pp' (my initials) ; thus I renamed the directory wspp instead of ws and the main entry point became http://yourmoodle/wspp/wsdl_pp.php

In the meantime Open Knowledge Technologies, now named Remote Learner improved internally its version, by merging some of my code, and recently documented it in chapter 14 of the PACKT book "Moodle 1.9 extension development".

Currently, (November 2010), revision 1.7 is available both at cipcnet and in Moodle CVS contrib area. On cipcnet you will find documentations and samples codes in php, Java and python.

Revision 1.7 runs best against a Moodle 1.9.x server, but can be installed on a Moodle 2.0. In that case, returned informations are 'Moodle 1.9 type' only. Moodle 2.0 specific data ( course completion, conditional activities, new File API ...) are not supported.

Others Forks

• Lightwork Web Services use a lighter version for its specific processing of grades and assignments.

Installation

You may get it via git at https://github.com/patrickpollet/moodlews or get the lastest archive file at http://prope.insa-lyon.fr/~ppollet/moodlews/wspp_latest.tgz

See file INSTALL.TXT in the archive.

List of exchanged data types

All exchanged data types and supported operations are published in a single WSDL file.

• Data returned by 'get' and 'edit' operations are normally arrays of records named xxxRecord. A xxxRecord maps to a Moodle entity, such as course, user, group, cohort ... and contains the returned values. An extra filed, named 'error' is always present. This field will be empty if the operation was successful or otherwise contains a localized error message.

• Data expected by 'edit' operations are normally arrays of records named xxxDatum. Each of these records will contain the value to add, update or delete in the corresponding Moodle entity. The required action must be set in the attribute action that can be 'add', 'update' or 'delete' ( comparison will be done in a case-insensitive way).

• By using proxy classes generator utilities (wsdl2xxx) available in most programming languages supporting the Soap protocol, the corresponding classes will be generated ready for use.

List of supported operations

All exchanged data types and supported operations are published in a single WSDL file.

They are divided in four main groups :

• get_XXX operations that returns an array of selected information from Moodle. All returned data are normally arrays of records described in classes named GetXXXReturn such as GetCoursesReturn, GetGradesReturn, GetUsersReturn ... These arrays are arrays of xxxRecord such as ActivityRecord, CohortRecord, GroupRecord, UserRecord ... each of these records will a have the 'error' attribute set to empty if the operation was successful or an error message otherwise.

• edit_XXX operations that expect values to add/udpate or delete in Moodle. All data expected as input are normally arrays of records described in classes named EditXXXInput such as EditUsersInput, EditCoursesInput ... These array are arrays of xxxDatum such as CourseDatum, ForumDatum, GroupingDatum ... For each of these records, one must set an action field to 'add', 'udpate' or 'delete'. Returned data are described in classes named EditXXXOutput that are again arrays of xxxRecord ; each of these records will a have the 'error' attribute set to empty if the operation was successful or an error message otherwise.

• convenience methods named add_xxx, delete_xxx or update_xxx that perform the same operations as their edit_xxx counterparts but expect only one input record of type xxxDatum. In these cases, is not necessary to set the 'action' field to add/update or delete. This will be done internally. Returned data is the same as the edit_xxx operations, i.e. an array containing the completed record, with the error field set or not.

• other miscellaneous operations : login, logout, has_role_incourse ...

Developers familiar with the Java language should consult the MoodleWS javadoc page available here (updated at every release). Supported operations are described in class MoodleWSPortType.

Authentication

This Web Service uses only the login/password authentication method. In the first versions (less that 1.6.1) this account must be a account for which authentication could be done 'silently', that is not using an external Web Page such as CAS or Shibboleth.

Starting at revision 1.6.1, to avoid disclosing a real admin login/password to developers of other information systems you should install the new authentication plugin located in wspp/auth/webservice. Copy this folder into moodle/auth folder and go to your site administration/accounts/authentication and enable the Web Service plugin.

THIS IS NOT NEEDED WITH MOODLE 2.0 since we use the already installed webservice authentication plugin. Just make sure you enable it in Site Administration / Plugins /Authentication.

Then create a new account on your Moodle site, say wsaccess and set webservice as the authentication method. Give to this account all the required capabilities compatible with your site security and the operations you want to allow ... (for example if you do not want any add_user, add_course ..., don't give him the corresponding capabilities).

Now developers of external informations systems, connecting to Moodle via this Web Service account will not be allowed to connect the "regular way"...

Testing the Web Service with SoapUI

This is definitely the easiest way to make sure that the installation of the plugin has been successful. I you can understand french a demo video is here.

Writing a client in PHP

The easiest way to write clients in PHP is to use the supplied utility wsld2php.php.

On the client machine, that must have PHP 5.x and the php5 soap extension installed :

• Copy the wspp/wsdl2php.php and the wspp/clients/auth.php.dist file in some directory

• Rename the file aut.php.dist to auth.php and edit it to supply an username and a password for the user you want to use to access the Web Service. It could be an admin user or an user restricted to the 'webservice' authentication method.

• On the command line, run :

[code]

php ./wsdl2php.php http://yourmoodle/wspp/wsdl_pp.php

[/code]

• This will generate a PHP class, named MoodleWS.php with all supported operations declared as methods, and a set of proxy classes for all exchanged data types.

• It will also create a folder named tests with a PHP script for each available operation.

Documentation for operations and samples codes in PHP are available here

Writing a client in Java

The javadoc of all datatypes and operations is available here (updated at every release). Supported operations are described in class MoodleWSBindingStub

A sample code using Apache axis-1.4 library can be downloaded here

Efforts to provide clients using the KSoap2 library such as Android smartphones are described here

Extending the OK Tech Web Service

See this page on the git repository of the projet

The future

Starting at revision 1.8 released on github, the WSDL file is now generated from the PHPDocs comments inserted in code of the mdl_soapserver.class and of the associated datatypes. This considerably simplify the extension of the Web Service and the writing of the clients.

To access this simplified new version, just change the URL of the WSDL from http://yourmoodle/wspp/wsdl_pp.php to http://yourmoodle/wspp/wsdl_pp2.php. The address of the service script will be automatically changed to wspp/service_pp2.php

PHP samples codes are available here

and javadoc is here

and here the simplified version of the Java Test class