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.

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

Import

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

TODO....

Documentation