Migration Web services

This feature is part of Moodle Workplace™, which is available through Moodle Partners only.

Overview

Web services for the Moodle Workplace Migrations feature.

The following web services are available in Moodle Workplace for export and import:

tool_wp_perform_export
tool_wp_perform_import
tool_wp_get_export_file
tool_wp_get_export_status
tool_wp_get_import_status
tool_wp_delete_export
tool_wp_delete_import
tool_wp_export
tool_wp_export_file_preview
tool_wp_import

Standard Moodle LMS functionality is available for uploading a file, see Web services files handling

To see the exact description of the parameters and return values of these web services in your version of Moodle Workplace, please turn on the admin setting $CFG->enablewsdocumentation and navigate to Site administration > Plugins > Web services> API Documentation

Set up

Create a new service with the functions: tool_wp_perform_export, tool_wp_perform_import, tool_wp_get_export_file, tool_wp_get_export_status, tool_wp_get_import_status or add these functions to the existing service
Allow this service for everybody or for users who you want to be able to use them
Create tokens for the users, enable protocols, add capabilities to use protocols

See more information under Using web services

Export

The following examples use command-line calls using the REST protocol. The output is piped through jq command to display JSON in a more readable way. There are many ways to call web-services and there are other alternatives of how to parse JSON. Adjust commands as needed. Do not forget to replace the site name and the token with your token.

Dry run

First execute the web-service tool_wp_perform_export with the parameter dryrun=1, it will validate input, show some information but will not actually schedule an export. You must pass parameter exporter. If the exporter is not available the error message will be displayed. The error message contains the list of all available exporters. For example:

$ curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ --data 'wsfunction=tool_wp_perform_export&exporter=&dryrun=1&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq {

 "exception": "invalid_parameter_exception",
 "errorcode": "invalidparameter",
 "message": "Invalid parameter value detected (Could not find exporter \nChoose from: tool_certification\\tool_wp\\exporter\\certifications, tool_dynamicrule\\tool_wp\\exporter\\rules, tool_organisation\\tool_wp\\exporter\\jobs, tool_organisation\\tool_wp\\exporter\\orgstructure, tool_program\\tool_wp\\exporter\\programs, tool_reportbuilder\\tool_wp\\exporter\\customreports, tool_tenant\\tool_wp\\exporter\\tenants, tool_wp\\tool_wp\\exporter\\certificates, tool_wp\\tool_wp\\exporter\\cohorts, tool_wp\\tool_wp\\exporter\\coursecategories, tool_wp\\tool_wp\\exporter\\courses, tool_wp\\tool_wp\\exporter\\site, tool_wp\\tool_wp\\exporter\\users)"

}

Now try again with the exporter name:

$ curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ --data 'wsfunction=tool_wp_perform_export&exporter=tool_organisation\tool_wp\exporter\orgstructure&dryrun=1&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq {

   "id": 0,
   "settings": "{\"export_instances\":\"all\",\"select_frameworks\":[]}"

}

Because it is a dry-run, the id=0 is returned (export was not actually scheduled). The web service also returns the list of settings that will be applied to the export. You may wish to change some of these settings, for example, we can export only positions by adding &settings={"export_instances": "positions"} to the URL (to pass more settings use a different index). Consider html encoding settings parameter value, as depending on use, there might be issues when you pass it in request.

Schedule export

Call the web service tool_wp_perform_export without the dryrun=1 parameter. For example:

curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ --data 'wsfunction=tool_wp_perform_export&exporter=tool_organisation\tool_wp\exporter\orgstructure&settings={"export_instances": "positions"}&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq {

 "id": 19,
 "settings": "{\"export_instances\":\"positions\",\"select_frameworks\":[]}"

}

This call returned id 19, we will need it in the next command.

Get status of export

Call the web service tool_wp_get_export_status with id from previous example to retrieve the status of the export:

curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ --data 'wsfunction=tool_wp_get_export_status&exportid=72&wstoken=f1355062bead0eab2f3d101e54243e0d' \ | jq {

 "status": 2,
 "statusstr": "Scheduled",
 "progress": 0

}

Retrieve export file

After the next cron run on the server you can retrieve the export file. If the cron has not run yet this command will return an error "Export not ready". Successful return will look like this:

$ curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ --data 'wsfunction=tool_wp_get_export_file&exportid=19&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq [

 {
   "filename": "organisation-structure-frameworks-export-20210115-1534.zip",
   "filepath": "/",
   "filesize": 3396,
   "fileurl": "https://SITENAME/webservice/pluginfile.php/1/tool_wp/export/19/organisation-structure-frameworks-export-20210115-1534.zip",
   "timemodified": 1610721298,
   "mimetype": "application/zip",
   "isexternalfile": false
 }

]

To download the file you need to add your token to the fileurl:

$ curl https://SITENAME/webservice/pluginfile.php/1/tool_wp/export/19/organisation-structure-frameworks-export-20210115-1534.zip?token=cf3788edbe41d7a89e963d9432b15331 > exportfile.zip

Additional parameters

Additionally, the tool_wp_perform_export web service has parameters:

tenant (int|string) - Database ID or non-numeric idnumber of the tenant where the export should be made
notenant (bool) - Perform export without the tenant (only for exporters that support this).

They can be used by global administrator or another user who has permission to switch between tenants.

Import

The web service tool_wp_perform_import is responsible for importing.

You can perform an import from an export file or upload a local file. To perform import from a previous Workplace export with id 19 add exportid=19 to the parameters. To perform import from a file you need to first upload a file and then use a draft item id as an argument, for example file=123456678 . Similar to the export, you can use dryrun=1 parameter to validate parameters without actually scheduling import.

Upload file

In this example we upload a local file positions.csv. It will be placed in a draft area for the current user. The script returns itemid of the draft area. It can be used only by the same user and will be automatically deleted by Moodle after two days.

Imagine we have a file with the name positions.csv with the following contents:

idnumber,parent,name,description,ismanager CEO,,Chief Executive Officer,Chief Executive Officer position,1 COO,CEO,Chief Operating Officer,Chief Operating Officer position,1 HMD,COO,Head of Marketing and Design,Head of Marketing and Design position,1 MCO,HMD,Marketing Consultant,Marketing Consultant position,0 OM,COO,Office Manager,Office Manager position,0

Note1: To demonstrate custom column mappings in this tutorial we called the last column "ismanager". If you call it "manager" or "globalmanager" you will not need to change the default mappings.

Note2: File name is important. If you choose to create a new framework during the import (default behavior), the file name will become a framework name

Standard Moodle LMS functionality is available for uploading a file, see Web services files handling, for example:

$ curl -X POST -F "image=@positions.csv" https://SITENAME/webservice/upload.php?token=cf3788edbe41d7a89e963d9432b15331 \ | jq [

 {
   "component": "user",
   "contextid": 567,
   "userid": "123",
   "filearea": "draft",
   "filename": "positions.csv",
   "filepath": "/",
   "itemid": 880413439,
   "license": "allrightsreserved",
   "author": "User User",
   "source": "O:8:\"stdClass\":1:{s:6:\"source\";s:13:\"positions.csv\";}"
 }

]

Dry-run

Example importing the export with id 19:

curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ --data 'wsfunction=tool_wp_perform_import&exportid=19&dryrun=1&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq

Example importing the file that is located in the draft area with itemid 880413439. This is a CSV file and there are several available importers, therefore an error will be raised. The error message will contain the list of available importers:

curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ --data 'wsfunction=tool_wp_perform_import&file=880413439&dryrun=1&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq {

 "exception": "invalid_parameter_exception",
 "errorcode": "invalidparameter",
 "message": "Invalid parameter value detected (More than one importer is available, importer must be specified\nChoose from: tool_organisation\\tool_wp\\importer\\departments_csv, tool_organisation\\tool_wp\\importer\\positions_csv)"

}

At the moment of writing this, there are two CSV importers in the Moodle Workplace distribution:

tool_organisation\tool_wp\importer\positions_csv
tool_organisation\tool_wp\importer\departments_csv

More importers may be added later to the Moodle Workplace and also more importers may be implemented by the plugins.

Let's execute the same web service tool_wp_perform_import specifying the positions importer:

$ curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ > --data 'wsfunction=tool_wp_perform_import&file=880413439&importer=tool_organisation\tool_wp\importer\positions_csv&dryrun=1&wstoken=cf3788edbe41d7a89e963d9432b15331' \ > | jq {

 "id": 0,
 "settings": "{\"target_framework\":\"new\",\"hierarchy\":\"selected\",\"identifier\":\"idnumber\",\"csvmapping:name\":\"name\",\"csvmapping:idnumber\":\"idnumber\",\"csvmapping:description\":\"description\",\"csvmapping:descriptionformat\":\"\",\"csvdefault:descriptionformat\":\"1\",\"csvmapping:parentid\":\"parent\",\"csvmapping:globalmanager\":\"\",\"csvmapping:departmentmanager\":\"\",\"select_framework\":null}"

}

The mapping of columns in the CSV file is picked automatically in the most cases, however the column ismanager was not mapped because the importer expects it to be called globalmanager (or manager). We can correct the mapping by adding to the request: &settings={"csvmapping:globalmanager": "ismanager"}

Scheduling import

Now we can execute the tool_wp_perform_import web service without dryrun parameter. The result will return the import id:

$ curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ --data 'wsfunction=tool_wp_perform_import&file=880413439&settings[0][name]=csvmapping:globalmanager&settings={"csvmapping:globalmanager":"ismanager"}&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq {

 "id": 56,
 "settings": "{\"target_framework\":\"new\",\"hierarchy\":\"selected\",\"identifier\":\"idnumber\",\"csvmapping:name\":\"name\",\"csvmapping:idnumber\":\"idnumber\",\"csvmapping:description\":\"description\",\"csvmapping:descriptionformat\":\"\",\"csvdefault:descriptionformat\":\"1\",\"csvmapping:parentid\":\"parent\",\"csvmapping:globalmanager\":\"ismanager\",\"csvmapping:departmentmanager\":\"\",\"select_framework\":null}"

}

The next cron run will execute this import.

Retrieving the import logs

Currently you can only see the import logs via the web interface. We will add a new web service for it soon.

Additional parameters

Additionally, the tool_wp_perform_import web service has parameters:

tenant (int|string) - Database ID or non-numeric idnumber of the tenant where the import should be made
notenant (bool) - Perform import without the tenant (only for importers that support this).

They can be used by global administrator or another user who has permission to switch between tenants.

Get status of import

Call the web service tool_wp_get_import_status with id from scheduling import example to retrieve the status of the import:

curl 'https://SITENAME/webservice/rest/server.php?moodlewsrestformat=json' \ --data 'wsfunction=tool_wp_get_import_status&importid=72&wstoken=f1355062bead0eab2f3d101e54243e0d' \ | jq {

 "status": 2,
 "statusstr": "Scheduled",
 "progress": 0

}