node.js client for moodle web services API
- moodle web services via REST protocol enabled.
$ npm install moodle-client
The client exposes promises API via bluebird implementation.
Call the init() function provided by the module to get a promise of a new
instance of the client. The promise fulfills with the instance of the client
ready to use for other requests.
var moodle_client = require("moodle-client");
moodle_client.init({
wwwroot: "http://localhost/moodle/",
token: "d457b5e5b0cc31c05ccf38628e4dfc14"
}).then(function(client) {
return do_something(client);
}).catch(function(err) {
console.log("Unable to initialize the client: " + err);
});
Instead of providing the token explicitly, you can let the client authenticate via provided username and password.
var moodle_client = require("moodle-client");
moodle_client.init({
wwwroot: "http://localhost/moodle/",
username: "mysystemusername",
password: "my$y$tem pa33w0rd"
}).then(function(client) {
return do_something(client);
}).catch(function(err) {
console.log("Unable to initialize the client: " + err);
});
Use the client's call() method to execute a web service function at the
remote moodle site. The returned promise fulfills with the data returned by the
remote function.
var moodle_client = require("moodle-client");
moodle_client.init({
wwwroot: "http://localhost/moodle/",
token: "d457b5e5b0cc31c05ccf38628e4dfc14"
}).then(function(client) {
return do_something(client);
}).catch(function(err) {
console.log("Unable to initialize the client: " + err);
});
function do_something(client) {
return client.call({
wsfunction: "core_webservice_get_site_info",
}).then(function(info) {
console.log("Hello %s, welcome to %s", info.fullname, info.sitename);
return;
});
}
To debug and/or log the client functionality, install and use the winston
logger.
var moodle_client = require("moodle-client");
var logger = require("winston");
logger.level = "debug";
logger.cli();
moodle_client.init({
logger: logger,
wwwroot: "http://localhost/moodle/",
token: "d457b5e5b0cc31c05ccf38628e4dfc14"
}).then(function(client) {
return do_something(client);
}).catch(function(err) {
console.log("Unable to initialize the client: " + err);
});
To use a custom web service, provide its shortname when creating a new instance
of the client. If the service is not specified, the client defaults to using
the moodle_mobile_app service.
var init = moodle_client.init({
wwwroot: "http://localhost/moodle/",
token: "d457b5e5b0cc31c05ccf38628e4dfc14",
service: "our_cohorts_management"
});
init.then(...);
To pass arguments to the web service function, provide them via the args
object. To use POST rather than the default GET request method, set the
method property of the call options.
init.then(function(client) {
return client.call({
wsfunction: "core_message_unblock_contacts",
method: "POST",
args: {
userids: [1, 2, 3, 4, 5]
}
}).then(function() {
console.log("Done");
return;
});
});
The client uses request-promise to actually perform the requests. Which in
turn uses qs to stringify the args into the query string. Please refer to the
qs module documentation for how to
pass complex data structures. For example, when calling the function
core_cohort_add_cohort_members the passed arguments should look something like
args: {
members: [
{
cohorttype: {
type: "id",
value: "1"
},
usertype: {
type: "id",
value: "3"
}
},
{
cohorttype: {
type: "id",
value: "1"
},
usertype: {
type: "id",
value: "4"
}
}
]
}
Additional settings can be provided via the settings object, such as the response data formatting. See moodle dev docs for details.
var mycall = client.call({
wsfunction: "local_myplugin_my_function",
args: {
answer: 42
},
settings: {
raw: false,
filter: true
}
);
mycall.then(...);
If you are connecting via HTTPS to a Moodle site with self-signed certificate,
you may need to set the strictSSL option to false.
var init = moodle_client.init({
wwwroot: "https://localhost/moodle/",
token: "d457b5eo5b0cc31c05ccf38628e4dfc14",
strictSSL: false
});
init.then(...);
Call the download() method of the client to download a file from the Moodle
file system. The returned promise fulfills with the buffer object with the file
contents.
client.download({
filepath: "/62/user/private/demo/remote.png",
preview: "bigthumb",
offline: true
}).then(function(filebuffer) {
fs.writeFile("/tmp/local.png", filebuffer, "binary");
return;
}).catch(function(err) {
console.log("Error downloading the file: " + err);
return;
});
The client can be used to upload files into the user's draft files area within the Moodle file system. Supported are both files with dynamically generated contents as well as files already stored in the local file system. See https://github.com/request/request#multipartform-data-multipart-form-uploads for details on how to specify the data in both cases.
var files = {
myfile1: {
value: "This text was uploaded by a client",
options: {
filename: "helloworld.txt",
contentType: "text/plain"
}
},
myfile2: fs.createReadStream("/tmp/upload.png"),
};
Once you have such a list of files prepared, call the upload() method to
upload them to the user's draft files area. The returned promise fulfills
with an array of objects describing the created files.
client.upload({
files: files
}).then(function(draftfiles) {
console.log(draftfiles);
return;
}).catch(function(err) {
console.log("Error uploading the file: " + err);
return;
});
The method allows you to hard-code the itemid within the user's draft area to upload files to and eventually the target path for uploaded files, too.
To make use of uploaded files in Moodle, you typically call a webservice
function that accepts the id of draft item containing the uploaded files. For
example, to copy files from the temporary draft files area to the persistent
private files area, use the function core_user_add_user_private_files:
client.upload({
files: files
}).then(function(draftfiles) {
// Copy files from the draft area to the persistent private files area.
return client.call({
wsfunction: "core_user_add_user_private_files",
args: {
draftid: draftfiles[0].itemid
}
}).then(function() {
console.log("Total of %d files uploaded to your private files area!", draftfiles.length);
return;
});
}).catch(function(err) {
console.log("Error uploading the file: " + err);
return;
});
- Added support for downloading files from Moodle. Credit goes to @MayaLekova for the initial implementation of the feature.
- Added support for uploading files to Moodle.
- Added basic support for travis-co prechecks.
- Massive non backwards compatible changes in the API.
- Now uses
request-promiseto actually perform the requests. - The API changed to return promises (via
bluebird). - The eventual authentication happens if needed during the initialization.
- The module does not provide
create()any more, useinit()returning the promise now.
- Fixed usage over HTTPS (#4). Added support for self-signed SSL certificates (#5).
- The initialization and API/signatures improved (#1).
- Added ability to authenticate by explicitly provided token (#3).
- Added tests.
- Initial release. The API should not be considered stable yet (as the version number suggests).