Integrating Moodle using Web Services
Welcome Back! In this blog we will learn more about Moodle. Please read my earlier blog to get to know about Moodle. We will cover below things in this blog –
- Moodle and web services: Will provide you with information on the basic concepts of Moodle web services
- External systems controlling Moodle: You will learn how to set up the Moodle web service for another application to control Moodle
- Users controlling Moodle: You will learn how to set up the Moodle web service for a user as the client
So, lets get started.
Web services overview
It has always been possible to extend Moodle via code (PHP and JavaScript). Due to Moodle’s open source code base, there can be no limitation to what code a developer is able to modify or extend.
Moodle has a number of APIs that provide an abstract layer for certain functionalities. Examples of this are the Portfolio API, Repository API, and the File API. These are great for programmers as they reduce the amount of code that has to be re-written. Web services enable other systems to perform operations
inside Moodle. Why would we want this? Well, there are three main scenarios we can think of:
- Other systems in your organization, for instance, the HR system, have to trigger certain actions in your VLE—once a student has been added to the system, an account has to be created in Moodle and enrolment in a number of courses has to take place.
- Web services simplify this process greatly.
- Mobile apps integrations.
Web services in Moodle
First of all, you have to activate web services, which can be accessed by navigating to Advanced features Enable web services. Second, you have to enable the Web services authentication plugin (Plugins | Authentication | Manage authentication). Once this has been done, go to Plugins | Web services Overview, which acts as a dashboard to set up Moodle web services.
Moodle supports four web services protocols—SOAP, REST, XML-RPC, and AMF. At least one protocol has to be enabled, which one depends entirely on the external application and the protocols supported. Clicking on the Enabled protocols link in the overview table when you go to Plugins | Web services | Manage protocols will guide you to this screen. Enable a protocol by toggling the show/hide icon in the Enable column.
Enabling web services for external systems
An external system is any application that accesses Moodle and its data in one way or the other. There are eight steps that have to be performed to complete the setup.
Create a specific user
Each application should have a separate user account. This way, you can control the capabilities that each external system is going to use. Our user is aptly called web service.
Check user capability
Depending on the protocol you’ve selected, you have to allow the respective permissions for the user. You achieve this by creating a new role with any of the four capabilities,
- webservice/amf:use
- webservice/rest:use
- webservice/soap:use
- or webservice/xmlrpc:use.
This role has to be assigned to the web services user(s) in the System context.
Select a service
A service is like a defined interface that an external application can connect to. It is a set of functions, which are covered next. Selecting a service takes place when you go to Plugins | Web services | External services. You have to Add a Custom service:
Each external service has to have Name, a unique Short name, and should be Enabled. A service has to be accessed via a token. The Authorised users only setting restricts this access to selected users. If it remains unticked, all users with the token permission can access the service.
Once you have saved the service, select the shown Add functions link.
Add functions
Moodle provides a number of functions that can be accessed via web services. This number will increase in upcoming versions, for example, to support additional features in mobile devices. Each function corresponds to a capability in Moodle roles.
The function(s) selected depend(s) on what tasks the external system has to perform and should be set up in liaison with the developer in charge. Since we are connecting to an HR system, we will allow a number of user-related functions:
Once you have added the selected functions, you will be shown the required capabilities that a user has to have to access the service. Make sure these have been allowed in the role assigned to the web services user.
Select a specific user
If you selected Authorised users only when you created the preceding service, you will have to select these user(s). This takes place when you go to Plugins | Web services | External services where you see a list of all the set up services. Select the Authorised users link, which will guide you to the familiar user selection screen. Select the web services user you created in step 1.
Create a token for a user
Web services use tokens for security. These are created for each user and can be added by going to Plugins | Web services | Manage tokens. To add a token, select a user (or multiple users), select the service to be accessed, and optionally specify an IP address (or range) and an expiry date as shown in the following screenshot:
Users will be able to access and reset their web services token by going to User account | Security keys in their Preferences if they have the moodle/webservice:createtoken capability.
Test the service
Once a web service is setup, functions have been selected, and users have been assigned, it is imperative that you test the service to make sure that it works and, more importantly, that only the required functionality has been opened up that is required by the external system. This is done by navigating to Development | Web service test client (select AMF test client if you use AMF).
First, you have to select Authentication method (simple for a username and
password, token for a security key), Protocol, and Function to test:
Once you have filled in the required values and executed the command (read the WARNING!), you will see a return value in the XML format. To receive a more meaningful message, change the Debug messages setting by going to Development | Debugging and then to DEVELOPER.
Enabling web services for users
It is sometimes necessary that users have to access web services directly instead of applications, for example, a developer who needs to execute test runs against the system. The process is a subset of steps already covered in the previous section and follows Users as clients with token section on the web services overview screen:
- Select a service.
- Add functions.
- Check the capability of the users. In addition to the protocol use capabilities,
the users have to have the moodle/webservice:createtoken URL allowed. - Test the service.
Conclusion
So, in this blog we saw how to integrate Moodle using web service and steps involved in it.