Migration Web services

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

Overview

Web services for the Moodle Workplace Migrations feature.

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

tool_wp_perform_export
tool_wp_perform_import
tool_wp_retrieve_export_file

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_retrieve_export_file 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&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq

{

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

}

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[0][name]=export_instances&settings[0][value]=positions to the URL (to pass more settings use a different index).

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[0][name]=export_instances&settings[0][value]=positions&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq

{

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

}

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

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_retrieve_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 retrieve 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 an export file 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.

$ 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

100 613 100 505 100 108 3686 788 --:--:-- --:--:-- --:--:-- 4442 {

 "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=212744242&tenant=t6&importer=tool_organisation\tool_wp\importer\positions_csv&dryrun=1&wstoken=cf3788edbe41d7a89e963d9432b15331' \ > | jq

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.