-

Note: You are currently viewing documentation for Moodle 3.10. Up-to-date documentation for the latest stable version of Moodle may be available here: Migration Web services.

Migration Web services: Difference between revisions

From MoodleDocs
Line 127: Line 127:
== Import ==
== Import ==


The web service '''tool_wp_perform_import''' is responsible for importing.
The web service <tt>tool_wp_perform_import</tt> 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.
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 <tt>exportid=19</tt> 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 <tt>file=123456678</tt> . Similar to the export, you can use <tt>dryrun=1</tt> parameter to validate parameters without actually scheduling import.


=== Upload file ===
=== Upload file ===

Revision as of 14:24, 28 January 2021

workplacelogo.png 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
  • tool_wp_get_export_status
  • tool_wp_get_import_status

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, 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 file

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

curl 'http://moodle.local/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_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 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": [
   {
     "name": "target_framework",
     "value": "new"
   },
   {
     "name": "hierarchy",
     "value": "selected"
   },
   {
     "name": "identifier",
     "value": "idnumber"
   },
   {
     "name": "csvmapping:name",
     "value": "name"
   },
   {
     "name": "csvmapping:idnumber",
     "value": "idnumber"
   },
   {
     "name": "csvmapping:description",
     "value": "description"
   },
   {
     "name": "csvmapping:descriptionformat",
     "value": ""
   },
   {
     "name": "csvdefault:descriptionformat",
     "value": "1"
   },
   {
     "name": "csvmapping:parentid",
     "value": "parent"
   },
   {
     "name": "csvmapping:globalmanager",
     "value": "manager"
   },
   {
     "name": "csvmapping:departmentmanager",
     "value": ""
   },
   {
     "name": "select_framework",
     "value": 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[0][name]=csvmapping:globalmanager&settings[0][value]=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[0][value]=ismanager&importer=tool_organisation\tool_wp\importer\positions_csv&wstoken=cf3788edbe41d7a89e963d9432b15331' \ | jq

{

 "id": 56,
 "settings": [
   ...
   {
     "name": "csvmapping:globalmanager",
     "value": "ismanager"
   },
   ...
 ]

}

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.

wp ws import log example.png

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.