Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.10.x will end 8 November 2021 (12 months).
  • Bug fixes for security issues in 3.10.x will end 9 May 2022 (18 months).
  • PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.

Differences Between: [Versions 310 and 402] [Versions 310 and 403]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * External API.
  19   *
  20   * @package    core_competency
  21   * @copyright  2016 Frédéric Massart - FMCorz.net
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  namespace core_competency;
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  require_once("$CFG->libdir/externallib.php");
  29  require_once("$CFG->libdir/grade/grade_scale.php");
  30  
  31  use context;
  32  use context_system;
  33  use context_course;
  34  use context_module;
  35  use context_helper;
  36  use context_user;
  37  use coding_exception;
  38  use external_api;
  39  use external_function_parameters;
  40  use external_value;
  41  use external_format_value;
  42  use external_single_structure;
  43  use external_multiple_structure;
  44  use invalid_parameter_exception;
  45  use required_capability_exception;
  46  use grade_scale;
  47  
  48  use core_competency\external\competency_exporter;
  49  use core_competency\external\competency_framework_exporter;
  50  use core_competency\external\course_competency_exporter;
  51  use core_competency\external\course_competency_settings_exporter;
  52  use core_competency\external\course_module_competency_exporter;
  53  use core_competency\external\evidence_exporter;
  54  use core_competency\external\performance_helper;
  55  use core_competency\external\plan_exporter;
  56  use core_competency\external\template_exporter;
  57  use core_competency\external\user_competency_exporter;
  58  use core_competency\external\user_competency_plan_exporter;
  59  use core_competency\external\user_evidence_competency_exporter;
  60  use core_competency\external\user_evidence_exporter;
  61  
  62  /**
  63   * External API class.
  64   *
  65   * @package    core_competency
  66   * @copyright  2016 Frédéric Massart - FMCorz.net
  67   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  68   */
  69  class external extends external_api {
  70  
  71      /**
  72       * Returns a prepared structure to use a context parameters.
  73       * @return external_single_structure
  74       */
  75      protected static function get_context_parameters() {
  76          $id = new external_value(
  77              PARAM_INT,
  78              'Context ID. Either use this value, or level and instanceid.',
  79              VALUE_DEFAULT,
  80              0
  81          );
  82          $level = new external_value(
  83              PARAM_ALPHA,
  84              'Context level. To be used with instanceid.',
  85              VALUE_DEFAULT,
  86              ''
  87          );
  88          $instanceid = new external_value(
  89              PARAM_INT,
  90              'Context instance ID. To be used with level',
  91              VALUE_DEFAULT,
  92              0
  93          );
  94          return new external_single_structure(array(
  95              'contextid' => $id,
  96              'contextlevel' => $level,
  97              'instanceid' => $instanceid,
  98          ));
  99      }
 100  
 101      /**
 102       * Returns description of create_competency_framework() parameters.
 103       *
 104       * @return \external_function_parameters
 105       */
 106      public static function create_competency_framework_parameters() {
 107          $structure = competency_framework_exporter::get_create_structure();
 108          $params = array('competencyframework' => $structure);
 109          return new external_function_parameters($params);
 110      }
 111  
 112      /**
 113       * Create a new competency framework
 114       *
 115       * @param array $competencyframework A single param with all the fields for a competency framework.
 116       * @return \stdClass The new record
 117       */
 118      public static function create_competency_framework($competencyframework) {
 119          global $PAGE;
 120  
 121          $params = self::validate_parameters(self::create_competency_framework_parameters(), array(
 122              'competencyframework' => $competencyframework
 123          ));
 124          $params = $params['competencyframework'];
 125  
 126          $context = self::get_context_from_params($params);
 127          self::validate_context($context);
 128          $output = $PAGE->get_renderer('core');
 129  
 130          unset($params['contextlevel']);
 131          unset($params['instanceid']);
 132          $params['contextid'] = $context->id;
 133  
 134          $params = (object) $params;
 135          $result = api::create_framework($params);
 136          $exporter = new competency_framework_exporter($result);
 137          $record = $exporter->export($output);
 138          return $record;
 139      }
 140  
 141      /**
 142       * Returns description of create_competency_framework() result value.
 143       *
 144       * @return \external_description
 145       */
 146      public static function create_competency_framework_returns() {
 147          return competency_framework_exporter::get_read_structure();
 148      }
 149  
 150      /**
 151       * Returns description of read_competency_framework() parameters.
 152       *
 153       * @return \external_function_parameters
 154       */
 155      public static function read_competency_framework_parameters() {
 156          $id = new external_value(
 157              PARAM_INT,
 158              'Data base record id for the framework',
 159              VALUE_REQUIRED
 160          );
 161  
 162          $params = array(
 163              'id' => $id,
 164          );
 165          return new external_function_parameters($params);
 166      }
 167  
 168      /**
 169       * Read a competency framework by id.
 170       *
 171       * @param int $id The id of the framework.
 172       * @return \stdClass
 173       */
 174      public static function read_competency_framework($id) {
 175          global $PAGE;
 176  
 177          $params = self::validate_parameters(self::read_competency_framework_parameters(), array(
 178              'id' => $id,
 179          ));
 180  
 181          $framework = api::read_framework($params['id']);
 182          self::validate_context($framework->get_context());
 183          $output = $PAGE->get_renderer('core');
 184          $exporter = new competency_framework_exporter($framework);
 185          $record = $exporter->export($output);
 186          return $record;
 187      }
 188  
 189      /**
 190       * Returns description of read_competency_framework() result value.
 191       *
 192       * @return \external_description
 193       */
 194      public static function read_competency_framework_returns() {
 195          return competency_framework_exporter::get_read_structure();
 196      }
 197  
 198      /**
 199       * Returns description of competency_viewed() parameters.
 200       *
 201       * @return \external_function_parameters
 202       */
 203      public static function competency_viewed_parameters() {
 204          $id = new external_value(
 205              PARAM_INT,
 206              'The competency id',
 207              VALUE_REQUIRED
 208          );
 209          $params = array(
 210              'id' => $id
 211          );
 212          return new external_function_parameters($params);
 213      }
 214  
 215      /**
 216       * Log event competency viewed.
 217       *
 218       * @param int $id The competency ID.
 219       * @return boolean
 220       */
 221      public static function competency_viewed($id) {
 222          $params = self::validate_parameters(self::competency_viewed_parameters(), array(
 223              'id' => $id
 224          ));
 225          return api::competency_viewed($params['id']);
 226      }
 227  
 228      /**
 229       * Returns description of competency_viewed() result value.
 230       *
 231       * @return \external_description
 232       */
 233      public static function competency_viewed_returns() {
 234          return new external_value(PARAM_BOOL, 'True if the event competency viewed was logged');
 235      }
 236  
 237      /**
 238       * Returns description of duplicate_competency_framework() parameters.
 239       *
 240       * @return \external_function_parameters
 241       */
 242      public static function duplicate_competency_framework_parameters() {
 243          $id = new external_value(
 244              PARAM_INT,
 245              'Data base record id for the framework',
 246              VALUE_REQUIRED
 247          );
 248  
 249          $params = array(
 250              'id' => $id,
 251          );
 252          return new external_function_parameters($params);
 253      }
 254  
 255      /**
 256       * Duplicate a competency framework
 257       *
 258       * @param int $id The competency framework id
 259       * @return boolean
 260       */
 261      public static function duplicate_competency_framework($id) {
 262          global $PAGE;
 263          $params = self::validate_parameters(self::duplicate_competency_framework_parameters(), array(
 264              'id' => $id,
 265          ));
 266  
 267          $framework = api::read_framework($params['id']);
 268          self::validate_context($framework->get_context());
 269  
 270          $output = $PAGE->get_renderer('core');
 271          $framework = api::duplicate_framework($params['id']);
 272          $exporter = new competency_framework_exporter($framework);
 273          $record = $exporter->export($output);
 274          return $record;
 275      }
 276  
 277      /**
 278       * Returns description of duplicate_competency_framework() result value.
 279       *
 280       * @return \external_description
 281       */
 282      public static function duplicate_competency_framework_returns() {
 283          return competency_framework_exporter::get_read_structure();
 284      }
 285  
 286      /**
 287       * Returns description of delete_competency_framework() parameters.
 288       *
 289       * @return \external_function_parameters
 290       */
 291      public static function delete_competency_framework_parameters() {
 292          $id = new external_value(
 293              PARAM_INT,
 294              'Data base record id for the framework',
 295              VALUE_REQUIRED
 296          );
 297  
 298          $params = array(
 299              'id' => $id,
 300          );
 301          return new external_function_parameters($params);
 302      }
 303  
 304      /**
 305       * Delete a competency framework
 306       *
 307       * @param int $id The competency framework id
 308       * @return boolean
 309       */
 310      public static function delete_competency_framework($id) {
 311          $params = self::validate_parameters(self::delete_competency_framework_parameters(), array(
 312              'id' => $id,
 313          ));
 314  
 315          $framework = api::read_framework($params['id']);
 316          self::validate_context($framework->get_context());
 317  
 318          return api::delete_framework($params['id']);
 319      }
 320  
 321      /**
 322       * Returns description of delete_competency_framework() result value.
 323       *
 324       * @return \external_description
 325       */
 326      public static function delete_competency_framework_returns() {
 327          return new external_value(PARAM_BOOL, 'True if the delete was successful');
 328      }
 329  
 330      /**
 331       * Returns description of update_competency_framework() parameters.
 332       *
 333       * @return \external_function_parameters
 334       */
 335      public static function update_competency_framework_parameters() {
 336          $structure = competency_framework_exporter::get_update_structure();
 337          $params = array('competencyframework' => $structure);
 338          return new external_function_parameters($params);
 339      }
 340  
 341      /**
 342       * Update an existing competency framework
 343       *
 344       * @param array $competencyframework An array with all the fields for a competency framework.
 345       * @return boolean
 346       */
 347      public static function update_competency_framework($competencyframework) {
 348  
 349          $params = self::validate_parameters(self::update_competency_framework_parameters(), array(
 350              'competencyframework' => $competencyframework
 351          ));
 352          $params = $params['competencyframework'];
 353  
 354          $framework = api::read_framework($params['id']);
 355          self::validate_context($framework->get_context());
 356  
 357          $params = (object) $params;
 358  
 359          return api::update_framework($params);
 360      }
 361  
 362      /**
 363       * Returns description of update_competency_framework() result value.
 364       *
 365       * @return \external_description
 366       */
 367      public static function update_competency_framework_returns() {
 368          return new external_value(PARAM_BOOL, 'True if the update was successful');
 369      }
 370  
 371      /**
 372       * Returns description of list_competency_frameworks() parameters.
 373       *
 374       * @return \external_function_parameters
 375       */
 376      public static function list_competency_frameworks_parameters() {
 377          $sort = new external_value(
 378              PARAM_ALPHANUMEXT,
 379              'Column to sort by.',
 380              VALUE_DEFAULT,
 381              'shortname'
 382          );
 383          $order = new external_value(
 384              PARAM_ALPHA,
 385              'Sort direction. Should be either ASC or DESC',
 386              VALUE_DEFAULT,
 387              ''
 388          );
 389          $skip = new external_value(
 390              PARAM_INT,
 391              'Skip this number of records before returning results',
 392              VALUE_DEFAULT,
 393              0
 394          );
 395          $limit = new external_value(
 396              PARAM_INT,
 397              'Return this number of records at most.',
 398              VALUE_DEFAULT,
 399              0
 400          );
 401          $includes = new external_value(
 402              PARAM_ALPHA,
 403              'What other contextes to fetch the frameworks from. (children, parents, self)',
 404              VALUE_DEFAULT,
 405              'children'
 406          );
 407          $onlyvisible = new external_value(
 408              PARAM_BOOL,
 409              'Only visible frameworks will be returned if visible true',
 410              VALUE_DEFAULT,
 411              false
 412          );
 413          $query = new external_value(
 414              PARAM_RAW,
 415              'A query string to filter the results',
 416              VALUE_DEFAULT,
 417              ''
 418          );
 419  
 420          $params = array(
 421              'sort' => $sort,
 422              'order' => $order,
 423              'skip' => $skip,
 424              'limit' => $limit,
 425              'context' => self::get_context_parameters(),
 426              'includes' => $includes,
 427              'onlyvisible' => $onlyvisible,
 428              'query' => $query,
 429          );
 430          return new external_function_parameters($params);
 431      }
 432  
 433      /**
 434       * List the existing competency frameworks
 435       *
 436       * @param int $sort
 437       * @param string $order
 438       * @param string $skip
 439       * @param int $limit
 440       * @param array $context
 441       * @param bool $includes
 442       * @param bool $onlyvisible
 443       * @param string $query
 444       *
 445       * @return array
 446       * @throws \required_capability_exception
 447       * @throws invalid_parameter_exception
 448       */
 449      public static function list_competency_frameworks($sort, $order, $skip, $limit, $context, $includes, $onlyvisible,
 450                                                        $query = '') {
 451          global $PAGE;
 452  
 453          $params = self::validate_parameters(self::list_competency_frameworks_parameters(), array(
 454              'sort' => $sort,
 455              'order' => $order,
 456              'skip' => $skip,
 457              'limit' => $limit,
 458              'context' => $context,
 459              'includes' => $includes,
 460              'onlyvisible' => $onlyvisible,
 461              'query' => $query,
 462          ));
 463  
 464          $context = self::get_context_from_params($params['context']);
 465          self::validate_context($context);
 466          $output = $PAGE->get_renderer('core');
 467  
 468          if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
 469              throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
 470          }
 471  
 472          $results = api::list_frameworks($params['sort'],
 473                                         $params['order'],
 474                                         $params['skip'],
 475                                         $params['limit'],
 476                                         $context,
 477                                         $params['includes'],
 478                                         $params['onlyvisible'],
 479                                         $params['query']);
 480          $records = array();
 481          foreach ($results as $result) {
 482              $exporter = new competency_framework_exporter($result);
 483              $record = $exporter->export($output);
 484              array_push($records, $record);
 485          }
 486          return $records;
 487      }
 488  
 489      /**
 490       * Returns description of list_competency_frameworks() result value.
 491       *
 492       * @return \external_description
 493       */
 494      public static function list_competency_frameworks_returns() {
 495          return new external_multiple_structure(competency_framework_exporter::get_read_structure());
 496      }
 497  
 498      /**
 499       * Returns description of count_competency_frameworks() parameters.
 500       *
 501       * @return \external_function_parameters
 502       */
 503      public static function count_competency_frameworks_parameters() {
 504          $includes = new external_value(
 505              PARAM_ALPHA,
 506              'What other contextes to fetch the frameworks from. (children, parents, self)',
 507              VALUE_DEFAULT,
 508              'children'
 509          );
 510  
 511          $params = array(
 512              'context' => self::get_context_parameters(),
 513              'includes' => $includes
 514          );
 515          return new external_function_parameters($params);
 516      }
 517  
 518      /**
 519       * Count the existing competency frameworks
 520       *
 521       * @param array $context
 522       * @param string $includes
 523       * @return int
 524       */
 525      public static function count_competency_frameworks($context, $includes) {
 526          $params = self::validate_parameters(self::count_competency_frameworks_parameters(), array(
 527              'context' => $context,
 528              'includes' => $includes
 529          ));
 530  
 531          $context = self::get_context_from_params($params['context']);
 532          self::validate_context($context);
 533  
 534          return api::count_frameworks($context, $params['includes']);
 535      }
 536  
 537      /**
 538       * Returns description of count_competency_frameworks() result value.
 539       *
 540       * @return \external_description
 541       */
 542      public static function count_competency_frameworks_returns() {
 543          return new external_value(PARAM_INT, 'The number of competency frameworks found.');
 544      }
 545  
 546      /**
 547       * Returns description of competency_framework_viewed() parameters.
 548       *
 549       * @return \external_function_parameters
 550       */
 551      public static function competency_framework_viewed_parameters() {
 552          $id = new external_value(
 553              PARAM_INT,
 554              'The competency framework id',
 555              VALUE_REQUIRED
 556          );
 557  
 558          $params = array(
 559              'id' => $id
 560          );
 561          return new external_function_parameters($params);
 562      }
 563  
 564      /**
 565       * Log event competency framework viewed.
 566       *
 567       * @param int $id The competency framework ID.
 568       * @return boolean
 569       */
 570      public static function competency_framework_viewed($id) {
 571          $params = self::validate_parameters(self::competency_framework_viewed_parameters(), array(
 572              'id' => $id
 573          ));
 574          return api::competency_framework_viewed($params['id']);
 575  
 576      }
 577  
 578      /**
 579       * Returns description of competency_framework_viewed() result value.
 580       *
 581       * @return \external_description
 582       */
 583      public static function competency_framework_viewed_returns() {
 584          return new external_value(PARAM_BOOL, 'True if the event competency framework was logged');
 585      }
 586  
 587      /**
 588       * Returns description of create_competency() parameters.
 589       *
 590       * @return \external_function_parameters
 591       */
 592      public static function create_competency_parameters() {
 593          $structure = competency_exporter::get_create_structure();
 594          $params = array('competency' => $structure);
 595          return new external_function_parameters($params);
 596      }
 597  
 598      /**
 599       * Create a new competency
 600       *
 601       * @param array $competency All the fields for a competency record (including id)
 602       * @return array the competency
 603       */
 604      public static function create_competency($competency) {
 605          global $PAGE;
 606  
 607          $params = self::validate_parameters(self::create_competency_parameters(), array(
 608              'competency' => $competency
 609          ));
 610  
 611          $params = $params['competency'];
 612          $framework = api::read_framework($params['competencyframeworkid']);
 613          $context = $framework->get_context();
 614          self::validate_context($context);
 615          $output = $PAGE->get_renderer('core');
 616  
 617          $params = (object) $params;
 618          $result = api::create_competency($params);
 619          $exporter = new competency_exporter($result, array('context' => $context));
 620          $record = $exporter->export($output);
 621          return $record;
 622      }
 623  
 624      /**
 625       * Returns description of create_competency() result value.
 626       *
 627       * @return \external_description
 628       */
 629      public static function create_competency_returns() {
 630          return competency_exporter::get_read_structure();
 631      }
 632  
 633      /**
 634       * Returns description of read_competency() parameters.
 635       *
 636       * @return \external_function_parameters
 637       */
 638      public static function read_competency_parameters() {
 639          $id = new external_value(
 640              PARAM_INT,
 641              'Data base record id for the competency',
 642              VALUE_REQUIRED
 643          );
 644  
 645          $params = array(
 646              'id' => $id,
 647          );
 648          return new external_function_parameters($params);
 649      }
 650  
 651      /**
 652       * Read a competency by id.
 653       *
 654       * @param int $id The id of the competency
 655       * @return \stdClass
 656       */
 657      public static function read_competency($id) {
 658          global $PAGE;
 659  
 660          $params = self::validate_parameters(self::read_competency_parameters(), array(
 661              'id' => $id,
 662          ));
 663  
 664          $competency = api::read_competency($params['id']);
 665          $context = $competency->get_context();
 666          self::validate_context($context);
 667          $output = $PAGE->get_renderer('core');
 668          $exporter = new competency_exporter($competency, array('context' => $context));
 669          $record = $exporter->export($output);
 670          return $record;
 671      }
 672  
 673      /**
 674       * Returns description of read_competency() result value.
 675       *
 676       * @return \external_description
 677       */
 678      public static function read_competency_returns() {
 679          return competency_exporter::get_read_structure();
 680      }
 681  
 682      /**
 683       * Returns description of delete_competency() parameters.
 684       *
 685       * @return \external_function_parameters
 686       */
 687      public static function delete_competency_parameters() {
 688          $id = new external_value(
 689              PARAM_INT,
 690              'Data base record id for the competency',
 691              VALUE_REQUIRED
 692          );
 693  
 694          $params = array(
 695              'id' => $id,
 696          );
 697          return new external_function_parameters($params);
 698      }
 699  
 700      /**
 701       * Delete a competency
 702       *
 703       * @param int $id The competency id
 704       * @return boolean
 705       */
 706      public static function delete_competency($id) {
 707          $params = self::validate_parameters(self::delete_competency_parameters(), array(
 708              'id' => $id,
 709          ));
 710  
 711          $competency = api::read_competency($params['id']);
 712          $context = $competency->get_context();
 713          self::validate_context($context);
 714  
 715          return api::delete_competency($params['id']);
 716      }
 717  
 718      /**
 719       * Returns description of delete_competency() result value.
 720       *
 721       * @return \external_description
 722       */
 723      public static function delete_competency_returns() {
 724          return new external_value(PARAM_BOOL, 'True if the delete was successful');
 725      }
 726  
 727      /**
 728       * Returns description of update_competency() parameters.
 729       *
 730       * @return \external_function_parameters
 731       */
 732      public static function update_competency_parameters() {
 733          $structure = competency_exporter::get_update_structure();
 734          $params = array('competency' => $structure);
 735          return new external_function_parameters($params);
 736      }
 737  
 738      /**
 739       * Update an existing competency
 740       *
 741       * @param array $competency The array of competency fields (id is required).
 742       * @return boolean
 743       */
 744      public static function update_competency($competency) {
 745          $params = self::validate_parameters(self::update_competency_parameters(), array(
 746              'competency' => $competency
 747          ));
 748          $params = $params['competency'];
 749  
 750          $competency = api::read_competency($params['id']);
 751          self::validate_context($competency->get_context());
 752  
 753          $params = (object) $params;
 754  
 755          return api::update_competency($params);
 756      }
 757  
 758      /**
 759       * Returns description of update_competency_framework() result value.
 760       *
 761       * @return \external_description
 762       */
 763      public static function update_competency_returns() {
 764          return new external_value(PARAM_BOOL, 'True if the update was successful');
 765      }
 766  
 767      /**
 768       * Returns description of list_competencies() parameters.
 769       *
 770       * @return \external_function_parameters
 771       */
 772      public static function list_competencies_parameters() {
 773          $filters = new external_multiple_structure(new external_single_structure(
 774              array(
 775                  'column' => new external_value(PARAM_ALPHANUMEXT, 'Column name to filter by'),
 776                  'value' => new external_value(PARAM_TEXT, 'Value to filter by. Must be exact match')
 777              )
 778          ));
 779          $sort = new external_value(
 780              PARAM_ALPHANUMEXT,
 781              'Column to sort by.',
 782              VALUE_DEFAULT,
 783              ''
 784          );
 785          $order = new external_value(
 786              PARAM_ALPHA,
 787              'Sort direction. Should be either ASC or DESC',
 788              VALUE_DEFAULT,
 789              ''
 790          );
 791          $skip = new external_value(
 792              PARAM_INT,
 793              'Skip this number of records before returning results',
 794              VALUE_DEFAULT,
 795              0
 796          );
 797          $limit = new external_value(
 798              PARAM_INT,
 799              'Return this number of records at most.',
 800              VALUE_DEFAULT,
 801              0
 802          );
 803  
 804          $params = array(
 805              'filters' => $filters,
 806              'sort' => $sort,
 807              'order' => $order,
 808              'skip' => $skip,
 809              'limit' => $limit
 810          );
 811          return new external_function_parameters($params);
 812      }
 813  
 814      /**
 815       * List the existing competency.
 816       *
 817       * @param string $filters
 818       * @param int $sort
 819       * @param string $order
 820       * @param string $skip
 821       * @param int $limit
 822       *
 823       * @return array
 824       * @throws \required_capability_exception
 825       * @throws invalid_parameter_exception
 826       */
 827      public static function list_competencies($filters, $sort, $order, $skip, $limit) {
 828          global $PAGE;
 829  
 830          $params = self::validate_parameters(self::list_competencies_parameters(), array(
 831              'filters' => $filters,
 832              'sort' => $sort,
 833              'order' => $order,
 834              'skip' => $skip,
 835              'limit' => $limit
 836          ));
 837  
 838          if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
 839              throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
 840          }
 841  
 842          $safefilters = array();
 843          $validcolumns = array('id', 'shortname', 'description', 'sortorder', 'idnumber',
 844              'parentid', 'competencyframeworkid');
 845          foreach ($params['filters'] as $filter) {
 846              if (!in_array($filter['column'], $validcolumns)) {
 847                  throw new invalid_parameter_exception('Filter column was invalid');
 848              }
 849              $safefilters[$filter['column']] = $filter['value'];
 850          }
 851  
 852          $context = null;
 853          if (isset($safefilters['competencyframeworkid'])) {
 854              $framework = api::read_framework($safefilters['competencyframeworkid']);
 855              $context = $framework->get_context();
 856          } else {
 857              $context = context_system::instance();
 858          }
 859  
 860          self::validate_context($context);
 861          $output = $PAGE->get_renderer('core');
 862  
 863          $results = api::list_competencies(
 864              $safefilters,
 865              $params['sort'],
 866              $params['order'],
 867              $params['skip'],
 868              $params['limit']
 869          );
 870  
 871          $records = array();
 872          foreach ($results as $result) {
 873              $exporter = new competency_exporter($result, array('context' => $context));
 874              $record = $exporter->export($output);
 875              array_push($records, $record);
 876          }
 877          return $records;
 878      }
 879  
 880      /**
 881       * Returns description of list_competencies() result value.
 882       *
 883       * @return \external_description
 884       */
 885      public static function list_competencies_returns() {
 886          return new external_multiple_structure(competency_exporter::get_read_structure());
 887      }
 888  
 889      /**
 890       * Returns description of search_competencies() parameters.
 891       *
 892       * @return \external_function_parameters
 893       */
 894      public static function search_competencies_parameters() {
 895          $searchtext = new external_value(
 896              PARAM_RAW,
 897              'Text to search for',
 898              VALUE_REQUIRED
 899          );
 900          $frameworkid = new external_value(
 901              PARAM_INT,
 902              'Competency framework id',
 903              VALUE_REQUIRED
 904          );
 905  
 906          $params = array(
 907              'searchtext' => $searchtext,
 908              'competencyframeworkid' => $frameworkid
 909          );
 910          return new external_function_parameters($params);
 911      }
 912  
 913      /**
 914       * List the existing competency frameworks
 915       *
 916       * @param string $searchtext Text to search.
 917       * @param int $competencyframeworkid Framework id.
 918       *
 919       * @return array
 920       */
 921      public static function search_competencies($searchtext, $competencyframeworkid) {
 922          global $PAGE;
 923  
 924          $params = self::validate_parameters(self::search_competencies_parameters(), array(
 925              'searchtext' => $searchtext,
 926              'competencyframeworkid' => $competencyframeworkid
 927          ));
 928  
 929          $framework = api::read_framework($params['competencyframeworkid']);
 930          $context = $framework->get_context();
 931          self::validate_context($context);
 932          $output = $PAGE->get_renderer('core');
 933  
 934          $results = api::search_competencies($params['searchtext'], $params['competencyframeworkid']);
 935          $records = array();
 936          foreach ($results as $result) {
 937              $exporter = new competency_exporter($result, array('context' => $context));
 938              $record = $exporter->export($output);
 939  
 940              array_push($records, $record);
 941          }
 942  
 943          return $records;
 944      }
 945  
 946      /**
 947       * Returns description of search_competencies() result value.
 948       *
 949       * @return \external_description
 950       */
 951      public static function search_competencies_returns() {
 952          return new external_multiple_structure(competency_exporter::get_read_structure());
 953      }
 954  
 955      /**
 956       * Returns description of count_competencies() parameters.
 957       *
 958       * @return \external_function_parameters
 959       */
 960      public static function count_competencies_parameters() {
 961          $filters = new external_multiple_structure(new external_single_structure(
 962              array(
 963                  'column' => new external_value(PARAM_ALPHANUMEXT, 'Column name to filter by'),
 964                  'value' => new external_value(PARAM_TEXT, 'Value to filter by. Must be exact match')
 965              )
 966          ));
 967  
 968          $params = array(
 969              'filters' => $filters,
 970          );
 971          return new external_function_parameters($params);
 972      }
 973  
 974      /**
 975       * Count the existing competency frameworks.
 976       *
 977       * @param string $filters Filters to use.
 978       * @return boolean
 979       */
 980      public static function count_competencies($filters) {
 981          $params = self::validate_parameters(self::count_competencies_parameters(), array(
 982              'filters' => $filters
 983          ));
 984  
 985          $safefilters = array();
 986          $validcolumns = array('id', 'shortname', 'description', 'sortorder', 'idnumber', 'parentid', 'competencyframeworkid');
 987          foreach ($params['filters'] as $filter) {
 988              if (!in_array($filter['column'], $validcolumns)) {
 989                  throw new invalid_parameter_exception('Filter column was invalid');
 990              }
 991              $safefilters[$filter['column']] = $filter['value'];
 992          }
 993  
 994          $context = null;
 995          if (isset($safefilters['competencyframeworkid'])) {
 996              $framework = api::read_framework($safefilters['competencyframeworkid']);
 997              $context = $framework->get_context();
 998          } else {
 999              $context = context_system::instance();
1000          }
1001  
1002          self::validate_context($context);
1003  
1004          return api::count_competencies($safefilters);
1005      }
1006  
1007      /**
1008       * Returns description of count_competencies() result value.
1009       *
1010       * @return \external_description
1011       */
1012      public static function count_competencies_returns() {
1013          return new external_value(PARAM_INT, 'The number of competencies found.');
1014      }
1015  
1016      /**
1017       * Returns description of set_parent_competency() parameters.
1018       *
1019       * @return \external_function_parameters
1020       */
1021      public static function set_parent_competency_parameters() {
1022          $competencyid = new external_value(
1023              PARAM_INT,
1024              'The competency id',
1025              VALUE_REQUIRED
1026          );
1027          $parentid = new external_value(
1028              PARAM_INT,
1029              'The new competency parent id',
1030              VALUE_REQUIRED
1031          );
1032          $params = array(
1033              'competencyid' => $competencyid,
1034              'parentid' => $parentid
1035          );
1036          return new external_function_parameters($params);
1037      }
1038  
1039      /**
1040       * Move the competency to a new parent.
1041       *
1042       * @param int $competencyid Competency id.
1043       * @param int $parentid Parent id.
1044       *
1045       * @return bool
1046       */
1047      public static function set_parent_competency($competencyid, $parentid) {
1048          $params = self::validate_parameters(self::set_parent_competency_parameters(), array(
1049              'competencyid' => $competencyid,
1050              'parentid' => $parentid
1051          ));
1052  
1053          $competency = api::read_competency($params['competencyid']);
1054          self::validate_context($competency->get_context());
1055  
1056          return api::set_parent_competency($params['competencyid'], $params['parentid']);
1057      }
1058  
1059      /**
1060       * Returns description of set_parent_competency() result value.
1061       *
1062       * @return \external_description
1063       */
1064      public static function set_parent_competency_returns() {
1065          return new external_value(PARAM_BOOL, 'True if the update was successful');
1066      }
1067  
1068      /**
1069       * Returns description of move_up_competency() parameters.
1070       *
1071       * @return \external_function_parameters
1072       */
1073      public static function move_up_competency_parameters() {
1074          $competencyid = new external_value(
1075              PARAM_INT,
1076              'The competency id',
1077              VALUE_REQUIRED
1078          );
1079          $params = array(
1080              'id' => $competencyid,
1081          );
1082          return new external_function_parameters($params);
1083      }
1084  
1085      /**
1086       * Change the sort order of a competency.
1087       *
1088       * @param int $competencyid Competency id.
1089       * @return boolean
1090       */
1091      public static function move_up_competency($competencyid) {
1092          $params = self::validate_parameters(self::move_up_competency_parameters(), array(
1093              'id' => $competencyid,
1094          ));
1095  
1096          $competency = api::read_competency($params['id']);
1097          self::validate_context($competency->get_context());
1098  
1099          return api::move_up_competency($params['id']);
1100      }
1101  
1102      /**
1103       * Returns description of move_up_competency() result value.
1104       *
1105       * @return \external_description
1106       */
1107      public static function move_up_competency_returns() {
1108          return new external_value(PARAM_BOOL, 'True if the update was successful');
1109      }
1110  
1111      /**
1112       * Returns description of move_down_competency() parameters.
1113       *
1114       * @return \external_function_parameters
1115       */
1116      public static function move_down_competency_parameters() {
1117          $competencyid = new external_value(
1118              PARAM_INT,
1119              'The competency id',
1120              VALUE_REQUIRED
1121          );
1122          $params = array(
1123              'id' => $competencyid,
1124          );
1125          return new external_function_parameters($params);
1126      }
1127  
1128      /**
1129       * Change the sort order of a competency.
1130       *
1131       * @param int $competencyid Competency id.
1132       * @return boolean
1133       */
1134      public static function move_down_competency($competencyid) {
1135          $params = self::validate_parameters(self::move_down_competency_parameters(), array(
1136              'id' => $competencyid,
1137          ));
1138  
1139          $competency = api::read_competency($params['id']);
1140          self::validate_context($competency->get_context());
1141  
1142          return api::move_down_competency($params['id']);
1143      }
1144  
1145      /**
1146       * Returns description of move_down_competency() result value.
1147       *
1148       * @return \external_description
1149       */
1150      public static function move_down_competency_returns() {
1151          return new external_value(PARAM_BOOL, 'True if the update was successful');
1152      }
1153  
1154      /**
1155       * Returns description of count_courses_using_competency() parameters.
1156       *
1157       * @return \external_function_parameters
1158       */
1159      public static function count_courses_using_competency_parameters() {
1160          $competencyid = new external_value(
1161              PARAM_INT,
1162              'The competency id',
1163              VALUE_REQUIRED
1164          );
1165          $params = array(
1166              'id' => $competencyid,
1167          );
1168          return new external_function_parameters($params);
1169      }
1170  
1171      /**
1172       * Count the courses (visible to this user) that use this competency.
1173       *
1174       * @param int $competencyid Competency id.
1175       * @return int
1176       */
1177      public static function count_courses_using_competency($competencyid) {
1178          $params = self::validate_parameters(self::count_courses_using_competency_parameters(), array(
1179              'id' => $competencyid,
1180          ));
1181  
1182          $competency = api::read_competency($params['id']);
1183          self::validate_context($competency->get_context());
1184  
1185          return api::count_courses_using_competency($params['id']);
1186      }
1187  
1188      /**
1189       * Returns description of count_courses_using_competency() result value.
1190       *
1191       * @return \external_description
1192       */
1193      public static function count_courses_using_competency_returns() {
1194          return new external_value(PARAM_INT, 'The number of courses using this competency');
1195      }
1196  
1197      /**
1198       * Returns description of count_competencies_in_course() parameters.
1199       *
1200       * @return \external_function_parameters
1201       */
1202      public static function count_competencies_in_course_parameters() {
1203          $courseid = new external_value(
1204              PARAM_INT,
1205              'The course id',
1206              VALUE_REQUIRED
1207          );
1208          $params = array(
1209              'id' => $courseid,
1210          );
1211          return new external_function_parameters($params);
1212      }
1213  
1214      /**
1215       * Count the competencies (visible to this user) in this course.
1216       *
1217       * @param int $courseid The course id to check.
1218       * @return int
1219       */
1220      public static function count_competencies_in_course($courseid) {
1221          $params = self::validate_parameters(self::count_competencies_in_course_parameters(), array(
1222              'id' => $courseid,
1223          ));
1224  
1225          self::validate_context(context_course::instance($params['id']));
1226  
1227          return api::count_competencies_in_course($params['id']);
1228      }
1229  
1230      /**
1231       * Returns description of count_competencies_in_course() result value.
1232       *
1233       * @return \external_description
1234       */
1235      public static function count_competencies_in_course_returns() {
1236          return new external_value(PARAM_INT, 'The number of competencies in this course.');
1237      }
1238  
1239      /**
1240       * Returns description of list_course_module_competencies() parameters.
1241       *
1242       * @return \external_function_parameters
1243       */
1244      public static function list_course_module_competencies_parameters() {
1245          $cmid = new external_value(
1246              PARAM_INT,
1247              'The course module id',
1248              VALUE_REQUIRED
1249          );
1250          $params = array(
1251              'cmid' => $cmid
1252          );
1253          return new external_function_parameters($params);
1254      }
1255  
1256      /**
1257       * List the course modules using this competency (visible to this user) in this course.
1258       *
1259       * @param int $cmid The course module id to check.
1260       * @return array
1261       */
1262      public static function list_course_module_competencies($cmid) {
1263          global $PAGE;
1264  
1265          $params = self::validate_parameters(self::list_course_module_competencies_parameters(), array(
1266              'cmid' => $cmid
1267          ));
1268  
1269          $context = context_module::instance($params['cmid']);
1270          self::validate_context($context);
1271  
1272          $output = $PAGE->get_renderer('core');
1273  
1274          $apiresult = api::list_course_module_competencies($params['cmid']);
1275          $result = array();
1276  
1277          foreach ($apiresult as $cmrecord) {
1278              $one = new \stdClass();
1279              $exporter = new competency_exporter($cmrecord['competency'], ['context' => $context]);
1280              $one->competency = $exporter->export($output);
1281              $exporter = new course_module_competency_exporter($cmrecord['coursemodulecompetency'], ['context' => $context]);
1282              $one->coursemodulecompetency = $exporter->export($output);
1283  
1284              $result[] = (array) $one;
1285          }
1286  
1287          return $result;
1288      }
1289  
1290      /**
1291       * Returns description of list_course_module_competencies() result value.
1292       *
1293       * @return \external_description
1294       */
1295      public static function list_course_module_competencies_returns() {
1296          return new external_multiple_structure(
1297              new external_single_structure(array(
1298                  'competency' => competency_exporter::get_read_structure(),
1299                  'coursemodulecompetency' => course_module_competency_exporter::get_read_structure()
1300              ))
1301          );
1302      }
1303  
1304      /**
1305       * Returns description of list_course_competencies() parameters.
1306       *
1307       * @return \external_function_parameters
1308       */
1309      public static function list_course_competencies_parameters() {
1310          $courseid = new external_value(
1311              PARAM_INT,
1312              'The course id',
1313              VALUE_REQUIRED
1314          );
1315          $params = array(
1316              'id' => $courseid,
1317          );
1318          return new external_function_parameters($params);
1319      }
1320  
1321      /**
1322       * Returns description of count_course_module_competencies() parameters.
1323       *
1324       * @return \external_function_parameters
1325       */
1326      public static function count_course_module_competencies_parameters() {
1327          $cmid = new external_value(
1328              PARAM_INT,
1329              'The course module id',
1330              VALUE_REQUIRED
1331          );
1332          $params = array(
1333              'cmid' => $cmid
1334          );
1335          return new external_function_parameters($params);
1336      }
1337  
1338      /**
1339       * List the course modules using this competency (visible to this user) in this course.
1340       *
1341       * @param int $cmid The course module id to check.
1342       * @return array
1343       */
1344      public static function count_course_module_competencies($cmid) {
1345          $params = self::validate_parameters(self::count_course_module_competencies_parameters(), array(
1346              'cmid' => $cmid
1347          ));
1348  
1349          $context = context_module::instance($params['cmid']);
1350          self::validate_context($context);
1351  
1352          return api::count_course_module_competencies($params['cmid']);
1353      }
1354  
1355      /**
1356       * Returns description of count_course_module_competencies() result value.
1357       *
1358       * @return \external_description
1359       */
1360      public static function count_course_module_competencies_returns() {
1361          return new external_value(PARAM_INT, 'The number of competencies found.');
1362      }
1363  
1364      /**
1365       * List the competencies (visible to this user) in this course.
1366       *
1367       * @param int $courseid The course id to check.
1368       * @return array
1369       */
1370      public static function list_course_competencies($courseid) {
1371          global $PAGE;
1372  
1373          $params = self::validate_parameters(self::list_course_competencies_parameters(), array(
1374              'id' => $courseid,
1375          ));
1376  
1377          $coursecontext = context_course::instance($params['id']);
1378          self::validate_context($coursecontext);
1379  
1380          $output = $PAGE->get_renderer('core');
1381  
1382          $competencies = api::list_course_competencies($params['id']);
1383          $result = array();
1384  
1385          $contextcache = array();
1386          $helper = new performance_helper();
1387          foreach ($competencies as $competency) {
1388              $context = $helper->get_context_from_competency($competency['competency']);
1389              $exporter = new competency_exporter($competency['competency'], array('context' => $context));
1390              $competencyrecord = $exporter->export($output);
1391              $exporter = new course_competency_exporter($competency['coursecompetency']);
1392              $coursecompetencyrecord = $exporter->export($output);
1393  
1394              $result[] = array(
1395                  'competency' => $competencyrecord,
1396                  'coursecompetency' => $coursecompetencyrecord
1397              );
1398          }
1399  
1400          return $result;
1401      }
1402  
1403      /**
1404       * Returns description of list_course_competencies() result value.
1405       *
1406       * @return \external_description
1407       */
1408      public static function list_course_competencies_returns() {
1409          return new external_multiple_structure(
1410              new external_single_structure(array(
1411                  'competency' => competency_exporter::get_read_structure(),
1412                  'coursecompetency' => course_competency_exporter::get_read_structure()
1413              ))
1414          );
1415      }
1416  
1417      /**
1418       * Returns description of add_competency_to_course() parameters.
1419       *
1420       * @return \external_function_parameters
1421       */
1422      public static function add_competency_to_course_parameters() {
1423          $courseid = new external_value(
1424              PARAM_INT,
1425              'The course id',
1426              VALUE_REQUIRED
1427          );
1428          $competencyid = new external_value(
1429              PARAM_INT,
1430              'The competency id',
1431              VALUE_REQUIRED
1432          );
1433          $params = array(
1434              'courseid' => $courseid,
1435              'competencyid' => $competencyid,
1436          );
1437          return new external_function_parameters($params);
1438      }
1439  
1440      /**
1441       * Count the competencies (visible to this user) in this course.
1442       *
1443       * @param int $courseid The course id to check.
1444       * @param int $competencyid Competency id.
1445       * @return int
1446       */
1447      public static function add_competency_to_course($courseid, $competencyid) {
1448          $params = self::validate_parameters(self::add_competency_to_course_parameters(), array(
1449              'courseid' => $courseid,
1450              'competencyid' => $competencyid,
1451          ));
1452          self::validate_context(context_course::instance($params['courseid']));
1453          return api::add_competency_to_course($params['courseid'], $params['competencyid']);
1454      }
1455  
1456      /**
1457       * Returns description of add_competency_to_course() result value.
1458       *
1459       * @return \external_description
1460       */
1461      public static function add_competency_to_course_returns() {
1462          return new external_value(PARAM_BOOL, 'True if successful.');
1463      }
1464  
1465      /**
1466       * Returns description of remove_competency_from_course() parameters.
1467       *
1468       * @return \external_function_parameters
1469       */
1470      public static function remove_competency_from_course_parameters() {
1471          $courseid = new external_value(
1472              PARAM_INT,
1473              'The course id',
1474              VALUE_REQUIRED
1475          );
1476          $competencyid = new external_value(
1477              PARAM_INT,
1478              'The competency id',
1479              VALUE_REQUIRED
1480          );
1481          $params = array(
1482              'courseid' => $courseid,
1483              'competencyid' => $competencyid,
1484          );
1485          return new external_function_parameters($params);
1486      }
1487  
1488      /**
1489       * Count the competencies (visible to this user) in this course.
1490       *
1491       * @param int $courseid The course id to check.
1492       * @param int $competencyid Competency id.
1493       * @return int
1494       */
1495      public static function remove_competency_from_course($courseid, $competencyid) {
1496          $params = self::validate_parameters(self::remove_competency_from_course_parameters(), array(
1497              'courseid' => $courseid,
1498              'competencyid' => $competencyid,
1499          ));
1500          self::validate_context(context_course::instance($params['courseid']));
1501          return api::remove_competency_from_course($params['courseid'], $params['competencyid']);
1502      }
1503  
1504      /**
1505       * Returns description of remove_competency_from_course() result value.
1506       *
1507       * @return \external_description
1508       */
1509      public static function remove_competency_from_course_returns() {
1510          return new external_value(PARAM_BOOL, 'True if successful.');
1511      }
1512  
1513      /**
1514       * Returns description of reorder_course_competency() parameters.
1515       *
1516       * @return \external_function_parameters
1517       */
1518      public static function reorder_course_competency_parameters() {
1519          $courseid = new external_value(
1520              PARAM_INT,
1521              'The course id',
1522              VALUE_REQUIRED
1523          );
1524          $competencyidfrom = new external_value(
1525              PARAM_INT,
1526              'The competency id we are moving',
1527              VALUE_REQUIRED
1528          );
1529          $competencyidto = new external_value(
1530              PARAM_INT,
1531              'The competency id we are moving to',
1532              VALUE_REQUIRED
1533          );
1534          $params = array(
1535              'courseid' => $courseid,
1536              'competencyidfrom' => $competencyidfrom,
1537              'competencyidto' => $competencyidto,
1538          );
1539          return new external_function_parameters($params);
1540      }
1541  
1542      /**
1543       * Change the order of course competencies.
1544       *
1545       * @param int $courseid The course id
1546       * @param int $competencyidfrom The competency to move.
1547       * @param int $competencyidto The competency to move to.
1548       * @return bool
1549       */
1550      public static function reorder_course_competency($courseid, $competencyidfrom, $competencyidto) {
1551          $params = self::validate_parameters(self::reorder_course_competency_parameters(), array(
1552              'courseid' => $courseid,
1553              'competencyidfrom' => $competencyidfrom,
1554              'competencyidto' => $competencyidto,
1555          ));
1556          self::validate_context(context_course::instance($params['courseid']));
1557          return api::reorder_course_competency($params['courseid'], $params['competencyidfrom'], $params['competencyidto']);
1558      }
1559  
1560      /**
1561       * Returns description of reorder_course_competency() result value.
1562       *
1563       * @return \external_description
1564       */
1565      public static function reorder_course_competency_returns() {
1566          return new external_value(PARAM_BOOL, 'True if successful.');
1567      }
1568  
1569      /**
1570       * Returns description of reorder_template_competency() parameters.
1571       *
1572       * @return \external_function_parameters
1573       */
1574      public static function reorder_template_competency_parameters() {
1575          $templateid = new external_value(
1576              PARAM_INT,
1577              'The template id',
1578              VALUE_REQUIRED
1579          );
1580          $competencyidfrom = new external_value(
1581              PARAM_INT,
1582              'The competency id we are moving',
1583              VALUE_REQUIRED
1584          );
1585          $competencyidto = new external_value(
1586              PARAM_INT,
1587              'The competency id we are moving to',
1588              VALUE_REQUIRED
1589          );
1590          $params = array(
1591              'templateid' => $templateid,
1592              'competencyidfrom' => $competencyidfrom,
1593              'competencyidto' => $competencyidto,
1594          );
1595          return new external_function_parameters($params);
1596      }
1597  
1598      /**
1599       * Change the order of template competencies.
1600       *
1601       * @param int $templateid The template id
1602       * @param int $competencyidfrom The competency to move.
1603       * @param int $competencyidto The competency to move to.
1604       * @return bool
1605       */
1606      public static function reorder_template_competency($templateid, $competencyidfrom, $competencyidto) {
1607          $params = self::validate_parameters(self::reorder_template_competency_parameters(), array(
1608              'templateid' => $templateid,
1609              'competencyidfrom' => $competencyidfrom,
1610              'competencyidto' => $competencyidto,
1611          ));
1612  
1613          $template = api::read_template($params['templateid']);
1614          self::validate_context($template->get_context());
1615  
1616          return api::reorder_template_competency($params['templateid'], $params['competencyidfrom'], $params['competencyidto']);
1617      }
1618  
1619      /**
1620       * Returns description of reorder_template_competency() result value.
1621       *
1622       * @return \external_description
1623       */
1624      public static function reorder_template_competency_returns() {
1625          return new external_value(PARAM_BOOL, 'True if successful.');
1626      }
1627  
1628      /**
1629       * Returns description of create_template() parameters.
1630       *
1631       * @return \external_function_parameters
1632       */
1633      public static function create_template_parameters() {
1634          $structure = template_exporter::get_create_structure();
1635          $params = array('template' => $structure);
1636          return new external_function_parameters($params);
1637      }
1638  
1639      /**
1640       * Create a new learning plan template
1641       *
1642       * @param array $template The list of fields for the template.
1643       * @return \stdClass Record of new template.
1644       */
1645      public static function create_template($template) {
1646          global $PAGE;
1647  
1648          $params = self::validate_parameters(self::create_template_parameters(), array('template' => $template));
1649          $params = $params['template'];
1650          $context = self::get_context_from_params($params);
1651          self::validate_context($context);
1652          $output = $PAGE->get_renderer('core');
1653  
1654          unset($params['contextlevel']);
1655          unset($params['instanceid']);
1656          $params = (object) $params;
1657          $params->contextid = $context->id;
1658  
1659          $result = api::create_template($params);
1660          $exporter = new template_exporter($result);
1661          $record = $exporter->export($output);
1662          return $record;
1663      }
1664  
1665      /**
1666       * Returns description of create_template() result value.
1667       *
1668       * @return \external_description
1669       */
1670      public static function create_template_returns() {
1671          return template_exporter::get_read_structure();
1672      }
1673  
1674      /**
1675       * Returns description of read_template() parameters.
1676       *
1677       * @return \external_function_parameters
1678       */
1679      public static function read_template_parameters() {
1680          $id = new external_value(
1681              PARAM_INT,
1682              'Data base record id for the template',
1683              VALUE_REQUIRED
1684          );
1685  
1686          $params = array(
1687              'id' => $id,
1688          );
1689          return new external_function_parameters($params);
1690      }
1691  
1692      /**
1693       * Read a learning plan template by id.
1694       *
1695       * @param int $id The id of the template.
1696       * @return \stdClass
1697       */
1698      public static function read_template($id) {
1699          global $PAGE;
1700  
1701          $params = self::validate_parameters(self::read_template_parameters(), array('id' => $id));
1702          $template = api::read_template($params['id']);
1703          self::validate_context($template->get_context());
1704          $output = $PAGE->get_renderer('core');
1705  
1706          $exporter = new template_exporter($template);
1707          $record = $exporter->export($output);
1708          return $record;
1709      }
1710  
1711      /**
1712       * Returns description of read_template() result value.
1713       *
1714       * @return \external_description
1715       */
1716      public static function read_template_returns() {
1717          return template_exporter::get_read_structure();
1718      }
1719  
1720      /**
1721       * Returns description of delete_template() parameters.
1722       *
1723       * @return \external_function_parameters
1724       */
1725      public static function delete_template_parameters() {
1726          $id = new external_value(
1727              PARAM_INT,
1728              'Data base record id for the template',
1729              VALUE_REQUIRED
1730          );
1731  
1732          $deleteplans = new external_value(
1733              PARAM_BOOL,
1734              'Boolean to indicate if plans must be deleted',
1735              VALUE_REQUIRED
1736          );
1737  
1738          $params = array(
1739              'id' => $id,
1740              'deleteplans' => $deleteplans
1741          );
1742          return new external_function_parameters($params);
1743      }
1744  
1745      /**
1746       * Delete a learning plan template
1747       *
1748       * @param int $id The learning plan template id
1749       * @param boolean $deleteplans True to delete the plans associated to template or false to unlink them
1750       * @return boolean
1751       */
1752      public static function delete_template($id, $deleteplans = true) {
1753          $params = self::validate_parameters(self::delete_template_parameters(), array(
1754              'id' => $id,
1755              'deleteplans' => $deleteplans,
1756          ));
1757  
1758          $template = api::read_template($params['id']);
1759          self::validate_context($template->get_context());
1760  
1761          return api::delete_template($params['id'], $params['deleteplans']);
1762      }
1763  
1764      /**
1765       * Returns description of delete_template() result value.
1766       *
1767       * @return \external_description
1768       */
1769      public static function delete_template_returns() {
1770          return new external_value(PARAM_BOOL, 'True if the delete was successful');
1771      }
1772  
1773      /**
1774       * Returns description of update_template() parameters.
1775       *
1776       * @return \external_function_parameters
1777       */
1778      public static function update_template_parameters() {
1779          $structure = template_exporter::get_update_structure();
1780          $params = array('template' => $structure);
1781          return new external_function_parameters($params);
1782      }
1783  
1784      /**
1785       * Update an existing learning plan template
1786       *
1787       * @param array $template The list of fields for the template.
1788       * @return boolean
1789       */
1790      public static function update_template($template) {
1791  
1792          $params = self::validate_parameters(self::update_template_parameters(), array('template' => $template));
1793          $params = $params['template'];
1794          $template = api::read_template($params['id']);
1795          self::validate_context($template->get_context());
1796  
1797          $params = (object) $params;
1798  
1799          return api::update_template($params);
1800      }
1801  
1802      /**
1803       * Returns description of update_template() result value.
1804       *
1805       * @return \external_description
1806       */
1807      public static function update_template_returns() {
1808          return new external_value(PARAM_BOOL, 'True if the update was successful');
1809      }
1810  
1811      /**
1812       * Returns description of duplicate_template() parameters.
1813       *
1814       * @return \external_function_parameters
1815       */
1816      public static function duplicate_template_parameters() {
1817          $templateid = new external_value(
1818              PARAM_INT,
1819              'The template id',
1820              VALUE_REQUIRED
1821          );
1822  
1823          $params = array(
1824              'id' => $templateid
1825          );
1826          return new external_function_parameters($params);
1827      }
1828  
1829      /**
1830       * Duplicate a learning plan template.
1831       *
1832       * @param int $id the id of the learning plan template to duplicate
1833       * @return boolean Record of new template.
1834       */
1835      public static function duplicate_template($id) {
1836          global $PAGE;
1837  
1838          $params = self::validate_parameters(self::duplicate_template_parameters(), array('id' => $id));
1839  
1840          $template = api::read_template($params['id']);
1841          self::validate_context($template->get_context());
1842          $output = $PAGE->get_renderer('core');
1843  
1844          $result = api::duplicate_template($params['id']);
1845          $exporter = new template_exporter($result);
1846          return $exporter->export($output);
1847      }
1848  
1849      /**
1850       * Returns description of duplicate_template() result value.
1851       *
1852       * @return \external_description
1853       */
1854      public static function duplicate_template_returns() {
1855          return template_exporter::get_read_structure();
1856      }
1857  
1858      /**
1859       * Returns description of list_templates() parameters.
1860       *
1861       * @return \external_function_parameters
1862       */
1863      public static function list_templates_parameters() {
1864          $sort = new external_value(
1865              PARAM_ALPHANUMEXT,
1866              'Column to sort by.',
1867              VALUE_DEFAULT,
1868              ''
1869          );
1870          $order = new external_value(
1871              PARAM_ALPHA,
1872              'Sort direction. Should be either ASC or DESC',
1873              VALUE_DEFAULT,
1874              ''
1875          );
1876          $skip = new external_value(
1877              PARAM_INT,
1878              'Skip this number of records before returning results',
1879              VALUE_DEFAULT,
1880              0
1881          );
1882          $limit = new external_value(
1883              PARAM_INT,
1884              'Return this number of records at most.',
1885              VALUE_DEFAULT,
1886              0
1887          );
1888          $includes = new external_value(
1889              PARAM_ALPHA,
1890              'What other contexts to fetch the templates from. (children, parents, self)',
1891              VALUE_DEFAULT,
1892              'children'
1893          );
1894          $onlyvisible = new external_value(
1895              PARAM_BOOL,
1896              'If should list only visible templates',
1897              VALUE_DEFAULT,
1898              false
1899          );
1900  
1901          $params = array(
1902              'sort' => $sort,
1903              'order' => $order,
1904              'skip' => $skip,
1905              'limit' => $limit,
1906              'context' => self::get_context_parameters(),
1907              'includes' => $includes,
1908              'onlyvisible' => $onlyvisible
1909          );
1910          return new external_function_parameters($params);
1911      }
1912  
1913      /**
1914       * List the existing learning plan templates
1915       *
1916       * @param string $sort Field to sort by.
1917       * @param string $order Sort order.
1918       * @param int $skip Limitstart.
1919       * @param int $limit Number of rows to return.
1920       * @param array $context
1921       * @param bool $includes
1922       * @param bool $onlyvisible
1923       *
1924       * @return array
1925       */
1926      public static function list_templates($sort, $order, $skip, $limit, $context, $includes, $onlyvisible) {
1927          global $PAGE;
1928  
1929          $params = self::validate_parameters(self::list_templates_parameters(), array(
1930              'sort' => $sort,
1931              'order' => $order,
1932              'skip' => $skip,
1933              'limit' => $limit,
1934              'context' => $context,
1935              'includes' => $includes,
1936              'onlyvisible' => $onlyvisible
1937          ));
1938  
1939          $context = self::get_context_from_params($params['context']);
1940          self::validate_context($context);
1941          $output = $PAGE->get_renderer('core');
1942  
1943          if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
1944              throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
1945          }
1946  
1947          $results = api::list_templates($params['sort'],
1948                                         $params['order'],
1949                                         $params['skip'],
1950                                         $params['limit'],
1951                                         $context,
1952                                         $params['includes'],
1953                                         $params['onlyvisible']);
1954          $records = array();
1955          foreach ($results as $result) {
1956              $exporter = new template_exporter($result);
1957              $record = $exporter->export($output);
1958              array_push($records, $record);
1959          }
1960          return $records;
1961      }
1962  
1963      /**
1964       * Returns description of list_templates() result value.
1965       *
1966       * @return \external_description
1967       */
1968      public static function list_templates_returns() {
1969          return new external_multiple_structure(template_exporter::get_read_structure());
1970      }
1971  
1972      /**
1973       * Returns description of count_templates() parameters.
1974       *
1975       * @return \external_function_parameters
1976       */
1977      public static function count_templates_parameters() {
1978          $includes = new external_value(
1979              PARAM_ALPHA,
1980              'What other contextes to fetch the frameworks from. (children, parents, self)',
1981              VALUE_DEFAULT,
1982              'children'
1983          );
1984  
1985          $params = array(
1986              'context' => self::get_context_parameters(),
1987              'includes' => $includes
1988          );
1989          return new external_function_parameters($params);
1990      }
1991  
1992      /**
1993       * Count the existing learning plan templates
1994       *
1995       * @param array $context
1996       * @param string $includes
1997       * @return int
1998       */
1999      public static function count_templates($context, $includes) {
2000          $params = self::validate_parameters(self::count_templates_parameters(), array(
2001              'context' => $context,
2002              'includes' => $includes
2003          ));
2004          $context = self::get_context_from_params($params['context']);
2005          self::validate_context($context);
2006  
2007          return api::count_templates($context, $includes);
2008      }
2009  
2010      /**
2011       * Returns description of count_templates() result value.
2012       *
2013       * @return \external_description
2014       */
2015      public static function count_templates_returns() {
2016          return new external_value(PARAM_INT, 'The number of learning plan templates found.');
2017      }
2018  
2019      /**
2020       * Returns description of count_templates_using_competency() parameters.
2021       *
2022       * @return \external_function_parameters
2023       */
2024      public static function count_templates_using_competency_parameters() {
2025          $competencyid = new external_value(
2026              PARAM_INT,
2027              'The competency id',
2028              VALUE_REQUIRED
2029          );
2030          $params = array(
2031              'id' => $competencyid,
2032          );
2033          return new external_function_parameters($params);
2034      }
2035  
2036      /**
2037       * Count the learning plan templates (visible to this user) that use this competency.
2038       *
2039       * @param int $competencyid Competency id.
2040       * @return int
2041       */
2042      public static function count_templates_using_competency($competencyid) {
2043          $params = self::validate_parameters(self::count_templates_using_competency_parameters(), array(
2044              'id' => $competencyid,
2045          ));
2046  
2047          $competency = api::read_competency($params['id']);
2048          self::validate_context($competency->get_context());
2049  
2050          return api::count_templates_using_competency($params['id']);
2051      }
2052  
2053      /**
2054       * Returns description of count_templates_using_competency() result value.
2055       *
2056       * @return \external_description
2057       */
2058      public static function count_templates_using_competency_returns() {
2059          return new external_value(PARAM_INT, 'The number of learning plan templates using this competency');
2060      }
2061  
2062      /**
2063       * Returns description of list_templates_using_competency() parameters.
2064       *
2065       * @return \external_function_parameters
2066       */
2067      public static function list_templates_using_competency_parameters() {
2068          $competencyid = new external_value(
2069              PARAM_INT,
2070              'The competency id',
2071              VALUE_REQUIRED
2072          );
2073          $params = array(
2074              'id' => $competencyid,
2075          );
2076          return new external_function_parameters($params);
2077      }
2078  
2079      /**
2080       * List the learning plan templates (visible to this user) that use this competency.
2081       *
2082       * @param int $competencyid Competency id.
2083       * @return array
2084       */
2085      public static function list_templates_using_competency($competencyid) {
2086          global $PAGE;
2087  
2088          $params = self::validate_parameters(self::list_templates_using_competency_parameters(), array(
2089              'id' => $competencyid,
2090          ));
2091  
2092          $competency = api::read_competency($params['id']);
2093          self::validate_context($competency->get_context());
2094          $output = $PAGE->get_renderer('core');
2095  
2096          $templates = api::list_templates_using_competency($params['id']);
2097          $records = array();
2098  
2099          foreach ($templates as $template) {
2100              $exporter = new template_exporter($template);
2101              $record = $exporter->export($output);
2102              $records[] = $record;
2103          }
2104  
2105          return $records;
2106      }
2107  
2108      /**
2109       * Returns description of list_templates_using_competency() result value.
2110       *
2111       * @return \external_description
2112       */
2113      public static function list_templates_using_competency_returns() {
2114          return new external_multiple_structure(template_exporter::get_read_structure());
2115      }
2116  
2117      /**
2118       * Returns description of count_competencies_in_template() parameters.
2119       *
2120       * @return \external_function_parameters
2121       */
2122      public static function count_competencies_in_template_parameters() {
2123          $templateid = new external_value(
2124              PARAM_INT,
2125              'The template id',
2126              VALUE_REQUIRED
2127          );
2128          $params = array(
2129              'id' => $templateid,
2130          );
2131          return new external_function_parameters($params);
2132      }
2133  
2134      /**
2135       * Count the competencies (visible to this user) in this learning plan template.
2136       *
2137       * @param int $templateid The template id to check
2138       * @return int
2139       */
2140      public static function count_competencies_in_template($templateid) {
2141          $params = self::validate_parameters(self::count_competencies_in_template_parameters(), array(
2142              'id' => $templateid,
2143          ));
2144          $template = api::read_template($params['id']);
2145          self::validate_context($template->get_context());
2146  
2147          return api::count_competencies_in_template($params['id']);
2148      }
2149  
2150      /**
2151       * Returns description of count_competencies_in_template() result value.
2152       *
2153       * @return \external_description
2154       */
2155      public static function count_competencies_in_template_returns() {
2156          return new external_value(PARAM_INT, 'The number of competencies in this learning plan template.');
2157      }
2158  
2159      /**
2160       * Returns description of list_competencies_in_template() parameters.
2161       *
2162       * @return \external_function_parameters
2163       */
2164      public static function list_competencies_in_template_parameters() {
2165          $templateid = new external_value(
2166              PARAM_INT,
2167              'The template id',
2168              VALUE_REQUIRED
2169          );
2170          $params = array(
2171              'id' => $templateid,
2172          );
2173          return new external_function_parameters($params);
2174      }
2175  
2176      /**
2177       * List the competencies (visible to this user) in this learning plan template.
2178       *
2179       * @param int $templateid Template id.
2180       * @return array
2181       */
2182      public static function list_competencies_in_template($templateid) {
2183          global $PAGE;
2184  
2185          $params = self::validate_parameters(self::list_competencies_in_template_parameters(), array(
2186              'id' => $templateid,
2187          ));
2188  
2189          $template = api::read_template($params['id']);
2190          self::validate_context($template->get_context());
2191          $output = $PAGE->get_renderer('core');
2192  
2193          $competencies = api::list_competencies_in_template($params['id']);
2194          $results = array();
2195  
2196          $helper = new performance_helper();
2197          foreach ($competencies as $competency) {
2198              $context = $helper->get_context_from_competency($competency);
2199              $exporter = new competency_exporter($competency, array('context' => $context));
2200              $record = $exporter->export($output);
2201              array_push($results, $record);
2202          }
2203          return $results;
2204      }
2205  
2206      /**
2207       * Returns description of list_competencies_in_template() result value.
2208       *
2209       * @return \external_description
2210       */
2211      public static function list_competencies_in_template_returns() {
2212          return new external_multiple_structure(competency_exporter::get_read_structure());
2213      }
2214  
2215      /**
2216       * Returns description of add_competency_to_template() parameters.
2217       *
2218       * @return \external_function_parameters
2219       */
2220      public static function add_competency_to_template_parameters() {
2221          $templateid = new external_value(
2222              PARAM_INT,
2223              'The template id',
2224              VALUE_REQUIRED
2225          );
2226          $competencyid = new external_value(
2227              PARAM_INT,
2228              'The competency id',
2229              VALUE_REQUIRED
2230          );
2231          $params = array(
2232              'templateid' => $templateid,
2233              'competencyid' => $competencyid,
2234          );
2235          return new external_function_parameters($params);
2236      }
2237  
2238      /**
2239       * Count the competencies (visible to this user) in this template.
2240       *
2241       * @param int $templateid Template id.
2242       * @param int $competencyid Competency id.
2243       * @return int
2244       */
2245      public static function add_competency_to_template($templateid, $competencyid) {
2246          global $PAGE;
2247          $params = self::validate_parameters(self::add_competency_to_template_parameters(), array(
2248              'templateid' => $templateid,
2249              'competencyid' => $competencyid,
2250          ));
2251  
2252          $template = api::read_template($params['templateid']);
2253          self::validate_context($template->get_context());
2254  
2255          return api::add_competency_to_template($params['templateid'], $params['competencyid']);
2256      }
2257  
2258      /**
2259       * Returns description of add_competency_to_template() result value.
2260       *
2261       * @return \external_description
2262       */
2263      public static function add_competency_to_template_returns() {
2264          return new external_value(PARAM_BOOL, 'True if successful.');
2265      }
2266  
2267      /**
2268       * Returns description of add_competency_to_plan() parameters.
2269       *
2270       * @return \external_function_parameters
2271       */
2272      public static function add_competency_to_plan_parameters() {
2273          $planid = new external_value(
2274              PARAM_INT,
2275              'The plan id',
2276              VALUE_REQUIRED
2277          );
2278          $competencyid = new external_value(
2279              PARAM_INT,
2280              'The competency id',
2281              VALUE_REQUIRED
2282          );
2283          $params = array(
2284              'planid' => $planid,
2285              'competencyid' => $competencyid,
2286          );
2287          return new external_function_parameters($params);
2288      }
2289  
2290      /**
2291       * add competency to a learning plan.
2292       *
2293       * @param int $planid Plan id.
2294       * @param int $competencyid Competency id.
2295       * @return int
2296       */
2297      public static function add_competency_to_plan($planid, $competencyid) {
2298          $params = self::validate_parameters(self::add_competency_to_plan_parameters(), array(
2299              'planid' => $planid,
2300              'competencyid' => $competencyid,
2301          ));
2302  
2303          $plan = api::read_plan($params['planid']);
2304          self::validate_context($plan->get_context());
2305  
2306          return api::add_competency_to_plan($params['planid'], $params['competencyid']);
2307      }
2308  
2309      /**
2310       * Returns description of add_competency_to_plan() result value.
2311       *
2312       * @return \external_description
2313       */
2314      public static function add_competency_to_plan_returns() {
2315          return new external_value(PARAM_BOOL, 'True if successful.');
2316      }
2317  
2318      /**
2319       * Returns description of remove_competency_from_plan() parameters.
2320       *
2321       * @return \external_function_parameters
2322       */
2323      public static function remove_competency_from_plan_parameters() {
2324          $planid = new external_value(
2325              PARAM_INT,
2326              'The plan id',
2327              VALUE_REQUIRED
2328          );
2329          $competencyid = new external_value(
2330              PARAM_INT,
2331              'The competency id',
2332              VALUE_REQUIRED
2333          );
2334          $params = array(
2335              'planid' => $planid,
2336              'competencyid' => $competencyid,
2337          );
2338          return new external_function_parameters($params);
2339      }
2340  
2341      /**
2342       * Remove a competency from plan.
2343       *
2344       * @param int $planid Plan id.
2345       * @param int $competencyid Competency id.
2346       * @return int
2347       */
2348      public static function remove_competency_from_plan($planid, $competencyid) {
2349          $params = self::validate_parameters(self::remove_competency_from_plan_parameters(), array(
2350              'planid' => $planid,
2351              'competencyid' => $competencyid,
2352          ));
2353          $plan = api::read_plan($params['planid']);
2354          self::validate_context($plan->get_context());
2355  
2356          return api::remove_competency_from_plan($params['planid'], $params['competencyid']);
2357      }
2358  
2359      /**
2360       * Returns description of remove_competency_from_plan() result value.
2361       *
2362       * @return \external_description
2363       */
2364      public static function remove_competency_from_plan_returns() {
2365          return new external_value(PARAM_BOOL, 'True if successful.');
2366      }
2367  
2368      /**
2369       * Returns description of remove_competency_from_template() parameters.
2370       *
2371       * @return \external_function_parameters
2372       */
2373      public static function remove_competency_from_template_parameters() {
2374          $templateid = new external_value(
2375              PARAM_INT,
2376              'The template id',
2377              VALUE_REQUIRED
2378          );
2379          $competencyid = new external_value(
2380              PARAM_INT,
2381              'The competency id',
2382              VALUE_REQUIRED
2383          );
2384          $params = array(
2385              'templateid' => $templateid,
2386              'competencyid' => $competencyid,
2387          );
2388          return new external_function_parameters($params);
2389      }
2390  
2391      /**
2392       * Returns description of reorder_plan_competency() parameters.
2393       *
2394       * @return \external_function_parameters
2395       */
2396      public static function reorder_plan_competency_parameters() {
2397          $planid = new external_value(
2398              PARAM_INT,
2399              'The plan id',
2400              VALUE_REQUIRED
2401          );
2402          $competencyidfrom = new external_value(
2403              PARAM_INT,
2404              'The competency id we are moving',
2405              VALUE_REQUIRED
2406          );
2407          $competencyidto = new external_value(
2408              PARAM_INT,
2409              'The competency id we are moving to',
2410              VALUE_REQUIRED
2411          );
2412          $params = array(
2413              'planid' => $planid,
2414              'competencyidfrom' => $competencyidfrom,
2415              'competencyidto' => $competencyidto,
2416          );
2417          return new external_function_parameters($params);
2418      }
2419  
2420      /**
2421       * Change the order of plan competencies.
2422       *
2423       * @param int $planid The plan id
2424       * @param int $competencyidfrom The competency to move.
2425       * @param int $competencyidto The competency to move to.
2426       * @return bool
2427       */
2428      public static function reorder_plan_competency($planid, $competencyidfrom, $competencyidto) {
2429          $params = self::validate_parameters(self::reorder_plan_competency_parameters(), array(
2430              'planid' => $planid,
2431              'competencyidfrom' => $competencyidfrom,
2432              'competencyidto' => $competencyidto,
2433          ));
2434  
2435          $plan = api::read_plan($params['planid']);
2436          self::validate_context($plan->get_context());
2437  
2438          return api::reorder_plan_competency($params['planid'], $params['competencyidfrom'], $params['competencyidto']);
2439      }
2440  
2441      /**
2442       * Returns description of reorder_plan_competency() result value.
2443       *
2444       * @return \external_description
2445       */
2446      public static function reorder_plan_competency_returns() {
2447          return new external_value(PARAM_BOOL, 'True if successful.');
2448      }
2449  
2450      /**
2451       * Returns description of external function parameters.
2452       *
2453       * @return \external_function_parameters
2454       */
2455      public static function user_competency_cancel_review_request_parameters() {
2456          return new external_function_parameters(array(
2457              'userid' => new external_value(PARAM_INT, 'The user ID'),
2458              'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2459          ));
2460      }
2461  
2462      /**
2463       * External function user_competency_cancel_review_request.
2464       *
2465       * @param int $userid The user ID.
2466       * @param int $competencyid The competency ID.
2467       * @return boolean
2468       */
2469      public static function user_competency_cancel_review_request($userid, $competencyid) {
2470          $params = self::validate_parameters(self::user_competency_cancel_review_request_parameters(), array(
2471              'userid' => $userid,
2472              'competencyid' => $competencyid
2473          ));
2474  
2475          $context = context_user::instance($params['userid']);
2476          self::validate_context($context);
2477  
2478          return api::user_competency_cancel_review_request($userid, $competencyid);
2479      }
2480  
2481      /**
2482       * Returns description of external function result value.
2483       *
2484       * @return \external_function_parameters
2485       */
2486      public static function user_competency_cancel_review_request_returns() {
2487          return new external_value(PARAM_BOOL, 'The success');
2488      }
2489  
2490      /**
2491       * Returns description of external function parameters.
2492       *
2493       * @return \external_function_parameters
2494       */
2495      public static function user_competency_request_review_parameters() {
2496          return new external_function_parameters(array(
2497              'userid' => new external_value(PARAM_INT, 'The user ID'),
2498              'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2499          ));
2500      }
2501  
2502      /**
2503       * External function user_competency_request_review.
2504       *
2505       * @param int $userid The user ID.
2506       * @param int $competencyid The competency ID.
2507       * @return boolean
2508       */
2509      public static function user_competency_request_review($userid, $competencyid) {
2510          $params = self::validate_parameters(self::user_competency_request_review_parameters(), array(
2511              'userid' => $userid,
2512              'competencyid' => $competencyid,
2513          ));
2514  
2515          $context = context_user::instance($params['userid']);
2516          self::validate_context($context);
2517  
2518          return api::user_competency_request_review($userid, $competencyid);
2519      }
2520  
2521      /**
2522       * Returns description of external function result value.
2523       *
2524       * @return \external_function_parameters
2525       */
2526      public static function user_competency_request_review_returns() {
2527          return new external_value(PARAM_BOOL, 'The success');
2528      }
2529  
2530      /**
2531       * Returns description of external function parameters.
2532       *
2533       * @return \external_function_parameters
2534       */
2535      public static function user_competency_start_review_parameters() {
2536          return new external_function_parameters(array(
2537              'userid' => new external_value(PARAM_INT, 'The user ID'),
2538              'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2539          ));
2540      }
2541  
2542      /**
2543       * External function user_competency_start_review.
2544       *
2545       * @param int $userid The user ID.
2546       * @param int $competencyid The competency ID.
2547       * @return boolean
2548       */
2549      public static function user_competency_start_review($userid, $competencyid) {
2550          $params = self::validate_parameters(self::user_competency_start_review_parameters(), array(
2551              'userid' => $userid,
2552              'competencyid' => $competencyid
2553          ));
2554  
2555          $context = context_user::instance($params['userid']);
2556          self::validate_context($context);
2557  
2558          return api::user_competency_start_review($userid, $competencyid);
2559      }
2560  
2561      /**
2562       * Returns description of external function result value.
2563       *
2564       * @return \external_function_parameters
2565       */
2566      public static function user_competency_start_review_returns() {
2567          return new external_value(PARAM_BOOL, 'The success');
2568      }
2569  
2570      /**
2571       * Returns description of external function parameters.
2572       *
2573       * @return \external_function_parameters
2574       */
2575      public static function user_competency_stop_review_parameters() {
2576          return new external_function_parameters(array(
2577              'userid' => new external_value(PARAM_INT, 'The user ID'),
2578              'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2579          ));
2580      }
2581  
2582      /**
2583       * External function user_competency_stop_review.
2584       *
2585       * @param int $userid The user ID.
2586       * @param int $competencyid The competency ID.
2587       * @return boolean
2588       */
2589      public static function user_competency_stop_review($userid, $competencyid) {
2590          $params = self::validate_parameters(self::user_competency_stop_review_parameters(), array(
2591              'userid' => $userid,
2592              'competencyid' => $competencyid
2593          ));
2594  
2595          $context = context_user::instance($params['userid']);
2596          self::validate_context($context);
2597  
2598          return api::user_competency_stop_review($userid, $competencyid);
2599      }
2600  
2601      /**
2602       * Returns description of external function result value.
2603       *
2604       * @return \external_function_parameters
2605       */
2606      public static function user_competency_stop_review_returns() {
2607          return new external_value(PARAM_BOOL, 'The success');
2608      }
2609  
2610      /**
2611       * Returns description of template_has_related_data() parameters.
2612       *
2613       * @return \external_function_parameters
2614       */
2615      public static function template_has_related_data_parameters() {
2616          $templateid = new external_value(
2617              PARAM_INT,
2618              'The template id',
2619              VALUE_REQUIRED
2620          );
2621          $params = array(
2622              'id' => $templateid,
2623          );
2624          return new external_function_parameters($params);
2625      }
2626  
2627      /**
2628       * Check if template has related data.
2629       *
2630       * @param int $templateid Template id.
2631       * @return boolean
2632       */
2633      public static function template_has_related_data($templateid) {
2634          $params = self::validate_parameters(self::template_has_related_data_parameters(), array(
2635              'id' => $templateid,
2636          ));
2637  
2638          $template = api::read_template($params['id']);
2639          self::validate_context($template->get_context());
2640  
2641          return api::template_has_related_data($params['id']);
2642      }
2643  
2644      /**
2645       * Returns description of template_has_related_data() result value.
2646       *
2647       * @return \external_description
2648       */
2649      public static function template_has_related_data_returns() {
2650          return new external_value(PARAM_BOOL, 'True if the template has related data');
2651      }
2652  
2653      /**
2654       * Count the competencies (visible to this user) in this learning plan template.
2655       *
2656       * @param int $templateid Template id.
2657       * @param int $competencyid Competency id.
2658       * @return int
2659       */
2660      public static function remove_competency_from_template($templateid, $competencyid) {
2661          $params = self::validate_parameters(self::remove_competency_from_template_parameters(), array(
2662              'templateid' => $templateid,
2663              'competencyid' => $competencyid,
2664          ));
2665          $template = api::read_template($params['templateid']);
2666          self::validate_context($template->get_context());
2667  
2668          return api::remove_competency_from_template($params['templateid'], $params['competencyid']);
2669      }
2670  
2671      /**
2672       * Returns description of remove_competency_from_template() result value.
2673       *
2674       * @return \external_description
2675       */
2676      public static function remove_competency_from_template_returns() {
2677          return new external_value(PARAM_BOOL, 'True if successful.');
2678      }
2679  
2680      /**
2681       * Returns description of create_plan() parameters.
2682       *
2683       * @return \external_function_parameters
2684       */
2685      public static function create_plan_parameters() {
2686          $structure = plan_exporter::get_create_structure();
2687          $params = array('plan' => $structure);
2688          return new external_function_parameters($params);
2689      }
2690  
2691      /**
2692       * Create a new learning plan.
2693       *
2694       * @param array $plan List of fields for the plan.
2695       * @return array New plan record.
2696       */
2697      public static function create_plan($plan) {
2698          global $PAGE;
2699  
2700          $params = self::validate_parameters(self::create_plan_parameters(), array('plan' => $plan));
2701          $params = $params['plan'];
2702  
2703          $context = context_user::instance($params['userid']);
2704          self::validate_context($context);
2705          $output = $PAGE->get_renderer('core');
2706  
2707          $params = (object) $params;
2708  
2709          $result = api::create_plan($params);
2710          $exporter = new plan_exporter($result, array('template' => null));
2711          return $exporter->export($output);
2712      }
2713  
2714      /**
2715       * Returns description of create_plan() result value.
2716       *
2717       * @return \external_description
2718       */
2719      public static function create_plan_returns() {
2720          return plan_exporter::get_read_structure();
2721      }
2722  
2723      /**
2724       * Returns description of update_plan() parameters.
2725       *
2726       * @return \external_function_parameters
2727       */
2728      public static function update_plan_parameters() {
2729          $structure = plan_exporter::get_update_structure();
2730          $params = array('plan' => $structure);
2731          return new external_function_parameters($params);
2732      }
2733  
2734      /**
2735       * Updates a new learning plan.
2736       *
2737       * @param array $plan Fields for the plan (id is required)
2738       * @return mixed
2739       */
2740      public static function update_plan($plan) {
2741          global $PAGE;
2742  
2743          $params = self::validate_parameters(self::update_plan_parameters(), array('plan' => $plan));
2744  
2745          $params = $params['plan'];
2746  
2747          $plan = api::read_plan($params['id']);
2748          self::validate_context($plan->get_context());
2749          $output = $PAGE->get_renderer('core');
2750  
2751          $params = (object) $params;
2752          $result = api::update_plan($params);
2753          $exporter = new plan_exporter($result, ['template' => $plan->get_template()]);
2754          return $exporter->export($output);
2755      }
2756  
2757      /**
2758       * Returns description of update_plan() result value.
2759       *
2760       * @return \external_description
2761       */
2762      public static function update_plan_returns() {
2763          return plan_exporter::get_read_structure();
2764      }
2765  
2766      /**
2767       * Returns description of complete_plan() parameters.
2768       *
2769       * @return \external_function_parameters
2770       */
2771      public static function complete_plan_parameters() {
2772          $planid = new external_value(
2773              PARAM_INT,
2774              'The plan id',
2775              VALUE_REQUIRED
2776          );
2777          $params = array('planid' => $planid);
2778          return new external_function_parameters($params);
2779      }
2780  
2781      /**
2782       * Complete Learning plan.
2783       *
2784       * @param int $planid plan id (id is required)
2785       * @return boolean
2786       */
2787      public static function complete_plan($planid) {
2788          $params = self::validate_parameters(self::complete_plan_parameters(), array(
2789              'planid' => $planid
2790          ));
2791  
2792          return api::complete_plan($params['planid']);
2793      }
2794  
2795      /**
2796       * Returns description of complete_plan() result value.
2797       *
2798       * @return \external_description
2799       */
2800      public static function complete_plan_returns() {
2801          return new external_value(PARAM_BOOL, 'True if completing learning plan was successful');
2802      }
2803  
2804      /**
2805       * Returns description of reopen_plan() parameters.
2806       *
2807       * @return \external_function_parameters
2808       */
2809      public static function reopen_plan_parameters() {
2810          $planid = new external_value(
2811              PARAM_INT,
2812              'The plan id',
2813              VALUE_REQUIRED
2814          );
2815          $params = array('planid' => $planid);
2816          return new external_function_parameters($params);
2817      }
2818  
2819      /**
2820       * Reopen Learning plan.
2821       *
2822       * @param int $planid plan id (id is required)
2823       * @return boolean
2824       */
2825      public static function reopen_plan($planid) {
2826          $params = self::validate_parameters(self::reopen_plan_parameters(), array(
2827              'planid' => $planid
2828          ));
2829  
2830          return api::reopen_plan($params['planid']);
2831      }
2832  
2833      /**
2834       * Returns description of reopen_plan() result value.
2835       *
2836       * @return \external_description
2837       */
2838      public static function reopen_plan_returns() {
2839          return new external_value(PARAM_BOOL, 'True if reopening learning plan was successful');
2840      }
2841  
2842      /**
2843       * Returns description of read_plan() parameters.
2844       *
2845       * @return \external_function_parameters
2846       */
2847      public static function read_plan_parameters() {
2848          $id = new external_value(
2849              PARAM_INT,
2850              'Data base record id for the plan',
2851              VALUE_REQUIRED
2852          );
2853          return new external_function_parameters(array('id' => $id));
2854      }
2855  
2856      /**
2857       * Read a plan by id.
2858       *
2859       * @param int $id The id of the plan.
2860       * @return \stdClass
2861       */
2862      public static function read_plan($id) {
2863          global $PAGE;
2864  
2865          $params = self::validate_parameters(self::read_plan_parameters(), array(
2866              'id' => $id,
2867          ));
2868  
2869          $plan = api::read_plan($params['id']);
2870          self::validate_context($plan->get_context());
2871          $output = $PAGE->get_renderer('core');
2872  
2873          $exporter = new plan_exporter($plan, array('template' => $plan->get_template()));
2874          $record = $exporter->export($output);
2875          return external_api::clean_returnvalue(self::read_plan_returns(), $record);
2876      }
2877  
2878      /**
2879       * Returns description of read_plan() result value.
2880       *
2881       * @return \external_description
2882       */
2883      public static function read_plan_returns() {
2884          return plan_exporter::get_read_structure();
2885      }
2886  
2887      /**
2888       * Returns description of delete_plan() parameters.
2889       *
2890       * @return \external_function_parameters
2891       */
2892      public static function delete_plan_parameters() {
2893          $id = new external_value(
2894              PARAM_INT,
2895              'Data base record id for the learning plan',
2896              VALUE_REQUIRED
2897          );
2898  
2899          $params = array(
2900              'id' => $id,
2901          );
2902          return new external_function_parameters($params);
2903      }
2904  
2905      /**
2906       * Delete a plan.
2907       *
2908       * @param int $id The plan id
2909       * @return boolean
2910       */
2911      public static function delete_plan($id) {
2912          $params = self::validate_parameters(self::delete_plan_parameters(), array(
2913              'id' => $id,
2914          ));
2915  
2916          $plan = api::read_plan($params['id']);
2917          self::validate_context($plan->get_context());
2918  
2919          return external_api::clean_returnvalue(self::delete_plan_returns(), api::delete_plan($params['id']));
2920      }
2921  
2922      /**
2923       * Returns description of delete_plan() result value.
2924       *
2925       * @return \external_description
2926       */
2927      public static function delete_plan_returns() {
2928          return new external_value(PARAM_BOOL, 'True if the delete was successful');
2929      }
2930  
2931      /**
2932       * Returns description of external function parameters.
2933       *
2934       * @return \external_function_parameters
2935       */
2936      public static function plan_cancel_review_request_parameters() {
2937          return new external_function_parameters(array(
2938              'id' => new external_value(PARAM_INT, 'The plan ID'),
2939          ));
2940      }
2941  
2942      /**
2943       * External function plan_cancel_review_request.
2944       *
2945       * @param int $id The plan ID.
2946       * @return boolean
2947       */
2948      public static function plan_cancel_review_request($id) {
2949          $params = self::validate_parameters(self::plan_cancel_review_request_parameters(), array(
2950              'id' => $id
2951          ));
2952  
2953          $plan = api::read_plan($id);
2954          self::validate_context($plan->get_context());
2955  
2956          return api::plan_cancel_review_request($plan);
2957      }
2958  
2959      /**
2960       * Returns description of external function result value.
2961       *
2962       * @return \external_function_parameters
2963       */
2964      public static function plan_cancel_review_request_returns() {
2965          return new external_value(PARAM_BOOL, 'The success');
2966      }
2967  
2968      /**
2969       * Returns description of external function parameters.
2970       *
2971       * @return \external_function_parameters
2972       */
2973      public static function plan_request_review_parameters() {
2974          return new external_function_parameters(array(
2975              'id' => new external_value(PARAM_INT, 'The plan ID'),
2976          ));
2977      }
2978  
2979      /**
2980       * External function plan_request_review.
2981       *
2982       * @param int $id The plan ID.
2983       * @return boolean
2984       */
2985      public static function plan_request_review($id) {
2986          $params = self::validate_parameters(self::plan_request_review_parameters(), array(
2987              'id' => $id
2988          ));
2989  
2990          $plan = api::read_plan($id);
2991          self::validate_context($plan->get_context());
2992  
2993          return api::plan_request_review($plan);
2994      }
2995  
2996      /**
2997       * Returns description of external function result value.
2998       *
2999       * @return \external_function_parameters
3000       */
3001      public static function plan_request_review_returns() {
3002          return new external_value(PARAM_BOOL, 'The success');
3003      }
3004  
3005      /**
3006       * Returns description of external function parameters.
3007       *
3008       * @return \external_function_parameters
3009       */
3010      public static function plan_start_review_parameters() {
3011          return new external_function_parameters(array(
3012              'id' => new external_value(PARAM_INT, 'The plan ID'),
3013          ));
3014      }
3015  
3016      /**
3017       * External function plan_start_review.
3018       *
3019       * @param int $id The plan ID.
3020       * @return boolean
3021       */
3022      public static function plan_start_review($id) {
3023          $params = self::validate_parameters(self::plan_start_review_parameters(), array(
3024              'id' => $id
3025          ));
3026  
3027          $plan = api::read_plan($id);
3028          self::validate_context($plan->get_context());
3029  
3030          return api::plan_start_review($plan);
3031      }
3032  
3033      /**
3034       * Returns description of external function result value.
3035       *
3036       * @return \external_function_parameters
3037       */
3038      public static function plan_start_review_returns() {
3039          return new external_value(PARAM_BOOL, 'The success');
3040      }
3041  
3042      /**
3043       * Returns description of external function parameters.
3044       *
3045       * @return \external_function_parameters
3046       */
3047      public static function plan_stop_review_parameters() {
3048          return new external_function_parameters(array(
3049              'id' => new external_value(PARAM_INT, 'The plan ID'),
3050          ));
3051      }
3052  
3053      /**
3054       * External function plan_stop_review.
3055       *
3056       * @param int $id The plan ID.
3057       * @return boolean
3058       */
3059      public static function plan_stop_review($id) {
3060          $params = self::validate_parameters(self::plan_stop_review_parameters(), array(
3061              'id' => $id
3062          ));
3063  
3064          $plan = api::read_plan($id);
3065          self::validate_context($plan->get_context());
3066  
3067          return api::plan_stop_review($plan);
3068      }
3069  
3070      /**
3071       * Returns description of external function result value.
3072       *
3073       * @return \external_function_parameters
3074       */
3075      public static function plan_stop_review_returns() {
3076          return new external_value(PARAM_BOOL, 'The success');
3077      }
3078  
3079      /**
3080       * Returns description of external function parameters.
3081       *
3082       * @return \external_function_parameters
3083       */
3084      public static function approve_plan_parameters() {
3085          return new external_function_parameters(array(
3086              'id' => new external_value(PARAM_INT, 'The plan ID'),
3087          ));
3088      }
3089  
3090      /**
3091       * External function approve_plan.
3092       *
3093       * @param int $id The plan ID.
3094       * @return boolean
3095       */
3096      public static function approve_plan($id) {
3097          $params = self::validate_parameters(self::approve_plan_parameters(), array(
3098              'id' => $id,
3099          ));
3100  
3101          $plan = api::read_plan($id);
3102          self::validate_context($plan->get_context());
3103  
3104          return api::approve_plan($plan);
3105      }
3106  
3107      /**
3108       * Returns description of external function result value.
3109       *
3110       * @return \external_function_parameters
3111       */
3112      public static function approve_plan_returns() {
3113          return new external_value(PARAM_BOOL, 'The success');
3114      }
3115  
3116      /**
3117       * Returns description of external function parameters.
3118       *
3119       * @return \external_function_parameters
3120       */
3121      public static function unapprove_plan_parameters() {
3122          return new external_function_parameters(array(
3123              'id' => new external_value(PARAM_INT, 'The plan ID'),
3124          ));
3125      }
3126  
3127      /**
3128       * External function unapprove_plan.
3129       *
3130       * @param int $id The plan ID.
3131       * @return boolean
3132       */
3133      public static function unapprove_plan($id) {
3134          $params = self::validate_parameters(self::unapprove_plan_parameters(), array(
3135              'id' => $id,
3136          ));
3137  
3138          $plan = api::read_plan($id);
3139          self::validate_context($plan->get_context());
3140  
3141          return api::unapprove_plan($plan);
3142      }
3143  
3144      /**
3145       * Returns description of external function result value.
3146       *
3147       * @return \external_function_parameters
3148       */
3149      public static function unapprove_plan_returns() {
3150          return new external_value(PARAM_BOOL, 'The success');
3151      }
3152  
3153      /**
3154       * External function parameters structure.
3155       *
3156       * @return \external_description
3157       */
3158      public static function list_plan_competencies_parameters() {
3159          return new external_function_parameters(array(
3160              'id' => new external_value(PARAM_INT, 'The plan ID.')
3161          ));
3162      }
3163  
3164      /**
3165       * List plan competencies.
3166       * @param  int $id The plan ID.
3167       * @return array
3168       */
3169      public static function list_plan_competencies($id) {
3170          global $PAGE;
3171  
3172          $params = self::validate_parameters(self::list_plan_competencies_parameters(), array('id' => $id));
3173          $id = $params['id'];
3174          $plan = api::read_plan($id);
3175          $usercontext = $plan->get_context();
3176          self::validate_context($usercontext);
3177          $output = $PAGE->get_renderer('core');
3178  
3179          $result = api::list_plan_competencies($plan);
3180  
3181          if ($plan->get('status') == plan::STATUS_COMPLETE) {
3182              $ucproperty = 'usercompetencyplan';
3183          } else {
3184              $ucproperty = 'usercompetency';
3185          }
3186  
3187          $helper = new performance_helper();
3188          foreach ($result as $key => $r) {
3189              $context = $helper->get_context_from_competency($r->competency);
3190              $scale = $helper->get_scale_from_competency($r->competency);
3191  
3192              $exporter = new competency_exporter($r->competency, array('context' => $context));
3193              $r->competency = $exporter->export($output);
3194  
3195              if ($r->usercompetency) {
3196                  $exporter = new user_competency_exporter($r->usercompetency, array('scale' => $scale));
3197                  $r->usercompetency = $exporter->export($output);
3198                  unset($r->usercompetencyplan);
3199              } else {
3200                  $exporter = new user_competency_plan_exporter($r->usercompetencyplan, array('scale' => $scale));
3201                  $r->usercompetencyplan = $exporter->export($output);
3202                  unset($r->usercompetency);
3203              }
3204          }
3205          return $result;
3206      }
3207  
3208      /**
3209       * External function return structure.
3210       *
3211       * @return \external_description
3212       */
3213      public static function list_plan_competencies_returns() {
3214          $uc = user_competency_exporter::get_read_structure();
3215          $ucp = user_competency_plan_exporter::get_read_structure();
3216  
3217          $uc->required = VALUE_OPTIONAL;
3218          $ucp->required = VALUE_OPTIONAL;
3219  
3220          return new external_multiple_structure(
3221              new external_single_structure(array(
3222                  'competency' => competency_exporter::get_read_structure(),
3223                  'usercompetency' => $uc,
3224                  'usercompetencyplan' => $ucp
3225              ))
3226          );
3227      }
3228  
3229      /**
3230       * Returns description of external function parameters.
3231       *
3232       * @return \external_function_parameters
3233       */
3234      public static function list_user_plans_parameters() {
3235          return new external_function_parameters(array(
3236              'userid' => new external_value(PARAM_INT, 'The user ID'),
3237          ));
3238      }
3239  
3240      /**
3241       * External function list_user_plans.
3242       *
3243       * @param int $userid The user ID.
3244       * @return boolean
3245       */
3246      public static function list_user_plans($userid) {
3247          global $PAGE;
3248          $params = self::validate_parameters(self::list_user_plans_parameters(), array(
3249              'userid' => $userid
3250          ));
3251  
3252          $context = context_user::instance($params['userid']);
3253          self::validate_context($context);
3254          $output = $PAGE->get_renderer('core');
3255  
3256          $response = array();
3257          $plans = api::list_user_plans($params['userid']);
3258          foreach ($plans as $plan) {
3259              $exporter = new plan_exporter($plan, array('template' => $plan->get_template()));
3260              $response[] = $exporter->export($output);
3261          }
3262  
3263          return $response;
3264      }
3265  
3266      /**
3267       * Returns description of external function result value.
3268       *
3269       * @return \external_function_parameters
3270       */
3271      public static function list_user_plans_returns() {
3272          return new external_multiple_structure(
3273              plan_exporter::get_read_structure()
3274          );
3275      }
3276  
3277      /**
3278       * Returns description of external function parameters.
3279       *
3280       * @return \external_description
3281       */
3282      public static function read_user_evidence_parameters() {
3283          return new external_function_parameters(array(
3284              'id' => new external_value(PARAM_INT, 'The user evidence ID.'),
3285          ));
3286      }
3287  
3288      /**
3289       * Delete a user evidence.
3290       *
3291       * @param int $id The evidence id
3292       * @return boolean
3293       */
3294      public static function read_user_evidence($id) {
3295          global $PAGE;
3296          $params = self::validate_parameters(self::read_user_evidence_parameters(), array('id' => $id));
3297  
3298          $userevidence = api::read_user_evidence($params['id']);
3299          $context = $userevidence->get_context();
3300          self::validate_context($context);
3301          $output = $PAGE->get_renderer('core');
3302  
3303          $exporter = new user_evidence_exporter($userevidence, array('context' => $context,
3304              'competencies' => $userevidence->get_competencies()));
3305          return $exporter->export($output);
3306      }
3307  
3308      /**
3309       * Returns description of external function result value.
3310       *
3311       * @return \external_description
3312       */
3313      public static function read_user_evidence_returns() {
3314          return user_evidence_exporter::get_read_structure();
3315      }
3316  
3317      /**
3318       * Returns description of external function parameters.
3319       *
3320       * @return \external_function_parameters
3321       */
3322      public static function delete_user_evidence_parameters() {
3323          return new external_function_parameters(array(
3324              'id' => new external_value(PARAM_INT, 'The user evidence ID.'),
3325          ));
3326      }
3327  
3328      /**
3329       * Delete a user evidence.
3330       *
3331       * @param int $id The evidence id
3332       * @return boolean
3333       */
3334      public static function delete_user_evidence($id) {
3335          $params = self::validate_parameters(self::delete_user_evidence_parameters(), array('id' => $id));
3336  
3337          $userevidence = api::read_user_evidence($params['id']);
3338          self::validate_context($userevidence->get_context());
3339  
3340          return api::delete_user_evidence($userevidence->get('id'));
3341      }
3342  
3343      /**
3344       * Returns description of external function result value.
3345       *
3346       * @return \external_description
3347       */
3348      public static function delete_user_evidence_returns() {
3349          return new external_value(PARAM_BOOL, 'True if the delete was successful');
3350      }
3351  
3352      /**
3353       * Returns description of external function parameters.
3354       *
3355       * @return \external_function_parameters
3356       */
3357      public static function create_user_evidence_competency_parameters() {
3358          return new external_function_parameters(array(
3359              'userevidenceid' => new external_value(PARAM_INT, 'The user evidence ID.'),
3360              'competencyid' => new external_value(PARAM_INT, 'The competency ID.'),
3361          ));
3362      }
3363  
3364      /**
3365       * Delete a user evidence competency relationship.
3366       *
3367       * @param int $userevidenceid The user evidence id.
3368       * @param int $competencyid The competency id.
3369       * @return boolean
3370       */
3371      public static function create_user_evidence_competency($userevidenceid, $competencyid) {
3372          global $PAGE;
3373          $params = self::validate_parameters(self::create_user_evidence_competency_parameters(), array(
3374              'userevidenceid' => $userevidenceid,
3375              'competencyid' => $competencyid,
3376          ));
3377  
3378          $userevidence = api::read_user_evidence($params['userevidenceid']);
3379          self::validate_context($userevidence->get_context());
3380  
3381          $relation = api::create_user_evidence_competency($userevidence, $competencyid);
3382          $exporter = new user_evidence_competency_exporter($relation);
3383          return $exporter->export($PAGE->get_renderer('core'));
3384      }
3385  
3386      /**
3387       * Returns description of external function result value.
3388       *
3389       * @return \external_description
3390       */
3391      public static function create_user_evidence_competency_returns() {
3392          return user_evidence_competency_exporter::get_read_structure();
3393      }
3394  
3395      /**
3396       * Returns description of external function parameters.
3397       *
3398       * @return \external_function_parameters
3399       */
3400      public static function delete_user_evidence_competency_parameters() {
3401          return new external_function_parameters(array(
3402              'userevidenceid' => new external_value(PARAM_INT, 'The user evidence ID.'),
3403              'competencyid' => new external_value(PARAM_INT, 'The competency ID.'),
3404          ));
3405      }
3406  
3407      /**
3408       * Delete a user evidence competency relationship.
3409       *
3410       * @param int $userevidenceid The user evidence id.
3411       * @param int $competencyid The competency id.
3412       * @return boolean
3413       */
3414      public static function delete_user_evidence_competency($userevidenceid, $competencyid) {
3415          $params = self::validate_parameters(self::delete_user_evidence_competency_parameters(), array(
3416              'userevidenceid' => $userevidenceid,
3417              'competencyid' => $competencyid,
3418          ));
3419  
3420          $userevidence = api::read_user_evidence($params['userevidenceid']);
3421          self::validate_context($userevidence->get_context());
3422  
3423          return api::delete_user_evidence_competency($userevidence, $params['competencyid']);
3424      }
3425  
3426      /**
3427       * Returns description of external function result value.
3428       *
3429       * @return \external_description
3430       */
3431      public static function delete_user_evidence_competency_returns() {
3432          return new external_value(PARAM_BOOL, 'True if the delete was successful');
3433      }
3434  
3435      /**
3436       * Returns description of external function parameters.
3437       *
3438       * @return \external_function_parameters
3439       */
3440      public static function request_review_of_user_evidence_linked_competencies_parameters() {
3441          return new external_function_parameters(array(
3442              'id' => new external_value(PARAM_INT, 'The user evidence ID.')
3443          ));
3444      }
3445  
3446      /**
3447       * Send user evidence competencies to review.
3448       *
3449       * @param int $id The user evidence id.
3450       * @return boolean
3451       */
3452      public static function request_review_of_user_evidence_linked_competencies($id) {
3453          $params = self::validate_parameters(self::request_review_of_user_evidence_linked_competencies_parameters(), array(
3454              'id' => $id
3455          ));
3456  
3457          $userevidence = api::read_user_evidence($id);
3458          self::validate_context($userevidence->get_context());
3459  
3460          return api::request_review_of_user_evidence_linked_competencies($id);
3461      }
3462  
3463      /**
3464       * Returns description of external function result value.
3465       *
3466       * @return \external_description
3467       */
3468      public static function request_review_of_user_evidence_linked_competencies_returns() {
3469          return new external_value(PARAM_BOOL, 'True if all competencies were send to review');
3470      }
3471  
3472  
3473      /**
3474       * Returns the description of the get_scale_values() parameters.
3475       *
3476       * @return external_function_parameters.
3477       */
3478      public static function get_scale_values_parameters() {
3479          $scaleid = new external_value(
3480              PARAM_INT,
3481              'The scale id',
3482              VALUE_REQUIRED
3483          );
3484          $params = array('scaleid' => $scaleid);
3485          return new external_function_parameters($params);
3486      }
3487  
3488      /**
3489       * Get the values associated with a scale.
3490       *
3491       * @param int $scaleid Scale ID
3492       * @return array Values for a scale.
3493       */
3494      public static function get_scale_values($scaleid) {
3495          global $DB;
3496          $params = self::validate_parameters(self::get_scale_values_parameters(),
3497              array(
3498                  'scaleid' => $scaleid,
3499              )
3500          );
3501          $context = context_system::instance();
3502          self::validate_context($context);
3503          // The following section is not learning plan specific and so has not been moved to the api.
3504          // Retrieve the scale value from the database.
3505          $scale = grade_scale::fetch(array('id' => $scaleid));
3506          $scalevalues = $scale->load_items();
3507          foreach ($scalevalues as $key => $value) {
3508              // Add a key (make the first value 1).
3509              $scalevalues[$key] = array(
3510                      'id' => $key + 1,
3511                      'name' => external_format_string($value, $context->id)
3512                  );
3513          }
3514          return $scalevalues;
3515      }
3516  
3517      /**
3518       * Returns description of get_scale_values() result value.
3519       *
3520       * @return external_multiple_structure
3521       */
3522      public static function get_scale_values_returns() {
3523          return new external_multiple_structure(
3524              new external_single_structure(array(
3525                  'id' => new external_value(PARAM_INT, 'Scale value ID'),
3526                  'name' => new external_value(PARAM_RAW, 'Scale value name')
3527              ))
3528          );
3529      }
3530  
3531  
3532      /**
3533       * Returns the description of the add_related_competency_parameters() parameters.
3534       *
3535       * @return external_function_parameters.
3536       */
3537      public static function add_related_competency_parameters() {
3538          $competencyid = new external_value(
3539              PARAM_INT,
3540              'The competency id',
3541              VALUE_REQUIRED
3542          );
3543          $relatedcompetencyid = new external_value(
3544              PARAM_INT,
3545              'The related competency id',
3546              VALUE_REQUIRED
3547          );
3548          $params = array(
3549              'competencyid' => $competencyid,
3550              'relatedcompetencyid' => $relatedcompetencyid
3551          );
3552          return new external_function_parameters($params);
3553      }
3554  
3555      /**
3556       * Adds a related competency.
3557       *
3558       * @param int $competencyid
3559       * @param int $relatedcompetencyid
3560       * @return bool
3561       */
3562      public static function add_related_competency($competencyid, $relatedcompetencyid) {
3563          $params = self::validate_parameters(self::add_related_competency_parameters(), array(
3564              'competencyid' => $competencyid,
3565              'relatedcompetencyid' => $relatedcompetencyid
3566          ));
3567          $competency = api::read_competency($params['competencyid']);
3568          self::validate_context($competency->get_context());
3569  
3570          return api::add_related_competency($params['competencyid'], $params['relatedcompetencyid']);
3571      }
3572  
3573      /**
3574       * Returns description of add_related_competency_returns() result value.
3575       *
3576       * @return external_description
3577       */
3578      public static function add_related_competency_returns() {
3579          return new external_value(PARAM_BOOL, 'True if successful.');
3580      }
3581  
3582      /**
3583       * Returns the description of the remove_related_competency_parameters() parameters.
3584       *
3585       * @return external_function_parameters.
3586       */
3587      public static function remove_related_competency_parameters() {
3588          $competencyid = new external_value(
3589              PARAM_INT,
3590              'The competency id',
3591              VALUE_REQUIRED
3592          );
3593          $relatedcompetencyid = new external_value(
3594              PARAM_INT,
3595              'The related competency id',
3596              VALUE_REQUIRED
3597          );
3598          $params = array(
3599              'competencyid' => $competencyid,
3600              'relatedcompetencyid' => $relatedcompetencyid
3601          );
3602          return new external_function_parameters($params);
3603      }
3604  
3605      /**
3606       * Removes a related competency.
3607       *
3608       * @param int $competencyid
3609       * @param int $relatedcompetencyid
3610       * @return bool
3611       */
3612      public static function remove_related_competency($competencyid, $relatedcompetencyid) {
3613          $params = self::validate_parameters(self::remove_related_competency_parameters(), array(
3614              'competencyid' => $competencyid,
3615              'relatedcompetencyid' => $relatedcompetencyid
3616          ));
3617          $competency = api::read_competency($params['competencyid']);
3618          self::validate_context($competency->get_context());
3619  
3620          return api::remove_related_competency($params['competencyid'], $params['relatedcompetencyid']);
3621      }
3622  
3623      /**
3624       * Returns description of remove_related_competency_returns() result value.
3625       *
3626       * @return external_description
3627       */
3628      public static function remove_related_competency_returns() {
3629          return new external_value(PARAM_BOOL, 'True if successful.');
3630      }
3631  
3632      /**
3633       * Returns description of update_ruleoutcome_course_competency() parameters.
3634       *
3635       * @return \external_function_parameters
3636       */
3637      public static function set_course_competency_ruleoutcome_parameters() {
3638          $coursecompetencyid = new external_value(
3639              PARAM_INT,
3640              'Data base record id for the course competency',
3641              VALUE_REQUIRED
3642          );
3643  
3644          $ruleoutcome = new external_value(
3645              PARAM_INT,
3646              'Ruleoutcome value',
3647              VALUE_REQUIRED
3648          );
3649  
3650          $params = array(
3651              'coursecompetencyid' => $coursecompetencyid,
3652              'ruleoutcome' => $ruleoutcome,
3653          );
3654          return new external_function_parameters($params);
3655      }
3656  
3657      /**
3658       * Change the ruleoutcome of a course competency.
3659       *
3660       * @param int $coursecompetencyid The course competency id
3661       * @param int $ruleoutcome The ruleoutcome value
3662       * @return bool
3663       */
3664      public static function set_course_competency_ruleoutcome($coursecompetencyid, $ruleoutcome) {
3665          $params = self::validate_parameters(self::set_course_competency_ruleoutcome_parameters(), array(
3666              'coursecompetencyid' => $coursecompetencyid,
3667              'ruleoutcome' => $ruleoutcome,
3668          ));
3669  
3670          $coursecompetency = new course_competency($params['coursecompetencyid']);
3671          self::validate_context(context_course::instance($coursecompetency->get('courseid')));
3672  
3673          return api::set_course_competency_ruleoutcome($coursecompetency, $params['ruleoutcome']);
3674      }
3675  
3676      /**
3677       * Returns description of update_ruleoutcome_course_competency() result value.
3678       *
3679       * @return \external_value
3680       */
3681      public static function set_course_competency_ruleoutcome_returns() {
3682          return new external_value(PARAM_BOOL, 'True if the update was successful');
3683      }
3684  
3685  
3686      /**
3687       * Returns description of external function parameters.
3688       *
3689       * @return \external_function_parameters
3690       */
3691      public static function grade_competency_parameters() {
3692          $userid = new external_value(
3693              PARAM_INT,
3694              'User ID',
3695              VALUE_REQUIRED
3696          );
3697          $competencyid = new external_value(
3698              PARAM_INT,
3699              'Competency ID',
3700              VALUE_REQUIRED
3701          );
3702          $grade = new external_value(
3703              PARAM_INT,
3704              'New grade',
3705              VALUE_REQUIRED
3706          );
3707          $note = new external_value(
3708              PARAM_NOTAGS,
3709              'A note to attach to the evidence',
3710              VALUE_DEFAULT
3711          );
3712  
3713          $params = array(
3714              'userid' => $userid,
3715              'competencyid' => $competencyid,
3716              'grade' => $grade,
3717              'note' => $note,
3718          );
3719          return new external_function_parameters($params);
3720      }
3721  
3722      /**
3723       * Grade a competency.
3724       *
3725       * @param int $userid The user ID.
3726       * @param int $competencyid The competency id
3727       * @param int $grade The new grade value
3728       * @param string $note A note to attach to the evidence
3729       * @return bool
3730       */
3731      public static function grade_competency($userid, $competencyid, $grade, $note = null) {
3732          global $USER, $PAGE;
3733          $params = self::validate_parameters(self::grade_competency_parameters(), array(
3734              'userid' => $userid,
3735              'competencyid' => $competencyid,
3736              'grade' => $grade,
3737              'note' => $note
3738          ));
3739  
3740          $uc = api::get_user_competency($params['userid'], $params['competencyid']);
3741          self::validate_context($uc->get_context());
3742  
3743          $output = $PAGE->get_renderer('core');
3744          $evidence = api::grade_competency(
3745                  $uc->get('userid'),
3746                  $uc->get('competencyid'),
3747                  $params['grade'],
3748                  $params['note']
3749          );
3750  
3751          $scale = $uc->get_competency()->get_scale();
3752          $exporter = new evidence_exporter($evidence, [
3753              'actionuser' => $USER,
3754              'scale' => $scale,
3755              'usercompetency' => $uc,
3756              'usercompetencyplan' => null,
3757              'context' => $evidence->get_context()
3758          ]);
3759          return $exporter->export($output);
3760      }
3761  
3762      /**
3763       * Returns description of external function result value.
3764       *
3765       * @return \external_value
3766       */
3767      public static function grade_competency_returns() {
3768          return evidence_exporter::get_read_structure();
3769      }
3770  
3771      /**
3772       * Returns description of grade_competency_in_plan() parameters.
3773       *
3774       * @return \external_function_parameters
3775       */
3776      public static function grade_competency_in_plan_parameters() {
3777          $planid = new external_value(
3778              PARAM_INT,
3779              'Plan id',
3780              VALUE_REQUIRED
3781          );
3782          $competencyid = new external_value(
3783              PARAM_INT,
3784              'Competency id',
3785              VALUE_REQUIRED
3786          );
3787          $grade = new external_value(
3788              PARAM_INT,
3789              'New grade',
3790              VALUE_REQUIRED
3791          );
3792          $note = new external_value(
3793              PARAM_NOTAGS,
3794              'A note to attach to the evidence',
3795              VALUE_DEFAULT
3796          );
3797  
3798          $params = array(
3799              'planid' => $planid,
3800              'competencyid' => $competencyid,
3801              'grade' => $grade,
3802              'note' => $note
3803          );
3804          return new external_function_parameters($params);
3805      }
3806  
3807      /**
3808       * Grade a competency in a plan.
3809       *
3810       * @param int $planid The plan id
3811       * @param int $competencyid The competency id
3812       * @param int $grade The new grade value
3813       * @param string $note A note to add to the evidence
3814       * @return bool
3815       */
3816      public static function grade_competency_in_plan($planid, $competencyid, $grade, $note = null) {
3817          global $USER, $PAGE;
3818  
3819          $params = self::validate_parameters(self::grade_competency_in_plan_parameters(), array(
3820              'planid' => $planid,
3821              'competencyid' => $competencyid,
3822              'grade' => $grade,
3823              'note' => $note
3824          ));
3825  
3826          $plan = new plan($params['planid']);
3827          $context = $plan->get_context();
3828          self::validate_context($context);
3829          $output = $PAGE->get_renderer('core');
3830  
3831          $evidence = api::grade_competency_in_plan(
3832                  $plan->get('id'),
3833                  $params['competencyid'],
3834                  $params['grade'],
3835                  $params['note']
3836          );
3837          $competency = api::read_competency($params['competencyid']);
3838          $scale = $competency->get_scale();
3839          $exporter = new evidence_exporter($evidence, [
3840              'actionuser' => $USER,
3841              'scale' => $scale,
3842              'usercompetency' => null,
3843              'usercompetencyplan' => null,
3844              'context' => $evidence->get_context()
3845          ]);
3846          return $exporter->export($output);
3847      }
3848  
3849      /**
3850       * Returns description of grade_competency_in_plan() result value.
3851       *
3852       * @return \external_value
3853       */
3854      public static function grade_competency_in_plan_returns() {
3855          return evidence_exporter::get_read_structure();
3856      }
3857  
3858      /**
3859       * Returns description of user_competency_viewed() parameters.
3860       *
3861       * @return \external_function_parameters
3862       */
3863      public static function user_competency_viewed_parameters() {
3864          $usercompetencyid = new external_value(
3865              PARAM_INT,
3866              'The user competency id',
3867              VALUE_REQUIRED
3868          );
3869          $params = array(
3870              'usercompetencyid' => $usercompetencyid
3871          );
3872          return new external_function_parameters($params);
3873      }
3874  
3875      /**
3876       * Log user competency viewed event.
3877       *
3878       * @param int $usercompetencyid The user competency ID.
3879       * @return boolean
3880       */
3881      public static function user_competency_viewed($usercompetencyid) {
3882          $params = self::validate_parameters(self::user_competency_viewed_parameters(), array(
3883              'usercompetencyid' => $usercompetencyid
3884          ));
3885  
3886          $uc = api::get_user_competency_by_id($params['usercompetencyid']);
3887          $result = api::user_competency_viewed($uc);
3888  
3889          return $result;
3890      }
3891  
3892      /**
3893       * Returns description of user_competency_viewed() result value.
3894       *
3895       * @return \external_description
3896       */
3897      public static function user_competency_viewed_returns() {
3898          return new external_value(PARAM_BOOL, 'True if the event user competency viewed was logged');
3899      }
3900  
3901      /**
3902       * Returns description of user_competency_viewed_in_plan() parameters.
3903       *
3904       * @return \external_function_parameters
3905       */
3906      public static function user_competency_viewed_in_plan_parameters() {
3907          $competencyid = new external_value(
3908              PARAM_INT,
3909              'The competency id',
3910              VALUE_REQUIRED
3911          );
3912          $userid = new external_value(
3913              PARAM_INT,
3914              'The user id',
3915              VALUE_REQUIRED
3916          );
3917          $planid = new external_value(
3918              PARAM_INT,
3919              'The plan id',
3920              VALUE_REQUIRED
3921          );
3922          $params = array(
3923              'competencyid' => $competencyid,
3924              'userid' => $userid,
3925              'planid' => $planid
3926          );
3927          return new external_function_parameters($params);
3928      }
3929  
3930      /**
3931       * Log user competency viewed in plan event.
3932       *
3933       * @param int $competencyid The competency ID.
3934       * @param int $userid The user ID.
3935       * @param int $planid The plan ID.
3936       * @return boolean
3937       */
3938      public static function user_competency_viewed_in_plan($competencyid, $userid, $planid) {
3939          $params = self::validate_parameters(self::user_competency_viewed_in_plan_parameters(), array(
3940              'competencyid' => $competencyid,
3941              'userid' => $userid,
3942              'planid' => $planid
3943          ));
3944          $pl = api::get_plan_competency($params['planid'], $params['competencyid']);
3945          $result = api::user_competency_viewed_in_plan($pl->usercompetency, $params['planid']);
3946  
3947          return $result;
3948      }
3949  
3950      /**
3951       * Returns description of user_competency_viewed_in_plan() result value.
3952       *
3953       * @return \external_description
3954       */
3955      public static function user_competency_viewed_in_plan_returns() {
3956          return new external_value(PARAM_BOOL, 'True if the event user competency viewed in plan was logged');
3957      }
3958  
3959      /**
3960       * Returns description of user_competency_viewed_in_course() parameters.
3961       *
3962       * @return \external_function_parameters
3963       */
3964      public static function user_competency_viewed_in_course_parameters() {
3965          $competencyid = new external_value(
3966              PARAM_INT,
3967              'The competency id',
3968              VALUE_REQUIRED
3969          );
3970          $userid = new external_value(
3971              PARAM_INT,
3972              'The user id',
3973              VALUE_REQUIRED
3974          );
3975          $courseid = new external_value(
3976              PARAM_INT,
3977              'The course id',
3978              VALUE_REQUIRED
3979          );
3980          $params = array(
3981              'competencyid' => $competencyid,
3982              'userid' => $userid,
3983              'courseid' => $courseid
3984          );
3985          return new external_function_parameters($params);
3986      }
3987  
3988      /**
3989       * Log user competency viewed in course event.
3990       *
3991       * @param int $competencyid The competency ID.
3992       * @param int $userid The user ID.
3993       * @param int $courseid The course ID.
3994       * @return boolean
3995       */
3996      public static function user_competency_viewed_in_course($competencyid, $userid, $courseid) {
3997          $params = self::validate_parameters(self::user_competency_viewed_in_course_parameters(), array(
3998              'competencyid' => $competencyid,
3999              'userid' => $userid,
4000              'courseid' => $courseid
4001          ));
4002          $ucc = api::get_user_competency_in_course($params['courseid'], $params['userid'], $params['competencyid']);
4003          $result = api::user_competency_viewed_in_course($ucc);
4004  
4005          return $result;
4006      }
4007  
4008      /**
4009       * Returns description of user_competency_viewed_in_course() result value.
4010       *
4011       * @return \external_description
4012       */
4013      public static function user_competency_viewed_in_course_returns() {
4014          return new external_value(PARAM_BOOL, 'True if the event user competency viewed in course was logged');
4015      }
4016  
4017      /**
4018       * Returns description of user_competency_plan_viewed() parameters.
4019       *
4020       * @return \external_function_parameters
4021       */
4022      public static function user_competency_plan_viewed_parameters() {
4023          $competencyid = new external_value(
4024              PARAM_INT,
4025              'The competency id',
4026              VALUE_REQUIRED
4027          );
4028          $userid = new external_value(
4029              PARAM_INT,
4030              'The user id',
4031              VALUE_REQUIRED
4032          );
4033          $planid = new external_value(
4034              PARAM_INT,
4035              'The plan id',
4036              VALUE_REQUIRED
4037          );
4038          $params = array(
4039              'competencyid' => $competencyid,
4040              'userid' => $userid,
4041              'planid' => $planid
4042          );
4043          return new external_function_parameters($params);
4044      }
4045  
4046      /**
4047       * Log user competency plan viewed event.
4048       *
4049       * @param int $competencyid The competency ID.
4050       * @param int $userid The user ID.
4051       * @param int $planid The plan ID.
4052       * @return boolean
4053       */
4054      public static function user_competency_plan_viewed($competencyid, $userid, $planid) {
4055          $params = self::validate_parameters(self::user_competency_viewed_in_plan_parameters(), array(
4056              'competencyid' => $competencyid,
4057              'userid' => $userid,
4058              'planid' => $planid
4059          ));
4060          $pl = api::get_plan_competency($params['planid'], $params['competencyid']);
4061          $result = api::user_competency_plan_viewed($pl->usercompetencyplan);
4062  
4063          return $result;
4064      }
4065  
4066      /**
4067       * Returns description of user_competency_plan_viewed() result value.
4068       *
4069       * @return \external_description
4070       */
4071      public static function user_competency_plan_viewed_returns() {
4072          return new external_value(PARAM_BOOL, 'True if the event user competency plan viewed was logged');
4073      }
4074  
4075      /**
4076       * Returns description of grade_competency_in_course() parameters.
4077       *
4078       * @return \external_function_parameters
4079       */
4080      public static function grade_competency_in_course_parameters() {
4081          $courseid = new external_value(
4082              PARAM_INT,
4083              'Course id',
4084              VALUE_REQUIRED
4085          );
4086          $userid = new external_value(
4087              PARAM_INT,
4088              'User id',
4089              VALUE_REQUIRED
4090          );
4091          $competencyid = new external_value(
4092              PARAM_INT,
4093              'Competency id',
4094              VALUE_REQUIRED
4095          );
4096          $grade = new external_value(
4097              PARAM_INT,
4098              'New grade',
4099              VALUE_REQUIRED
4100          );
4101          $note = new external_value(
4102              PARAM_NOTAGS,
4103              'A note to attach to the evidence',
4104              VALUE_DEFAULT
4105          );
4106  
4107          $params = array(
4108              'courseid' => $courseid,
4109              'userid' => $userid,
4110              'competencyid' => $competencyid,
4111              'grade' => $grade,
4112              'note' => $note,
4113          );
4114          return new external_function_parameters($params);
4115      }
4116  
4117      /**
4118       * Grade a competency in a course.
4119       *
4120       * @param int $courseid The course id
4121       * @param int $userid The user id
4122       * @param int $competencyid The competency id
4123       * @param int $grade The new grade value
4124       * @param string $note A note to add to the evidence
4125       * @return bool
4126       */
4127      public static function grade_competency_in_course($courseid, $userid, $competencyid, $grade, $note = null) {
4128          global $USER, $PAGE, $DB;
4129  
4130          $params = self::validate_parameters(self::grade_competency_in_course_parameters(), array(
4131              'courseid' => $courseid,
4132              'userid' => $userid,
4133              'competencyid' => $competencyid,
4134              'grade' => $grade,
4135              'note' => $note
4136          ));
4137  
4138          $course = $DB->get_record('course', array('id' => $params['courseid']));
4139          $context = context_course::instance($course->id);
4140          self::validate_context($context);
4141          $output = $PAGE->get_renderer('core');
4142  
4143          $evidence = api::grade_competency_in_course(
4144                  $params['courseid'],
4145                  $params['userid'],
4146                  $params['competencyid'],
4147                  $params['grade'],
4148                  $params['note']
4149          );
4150          $competency = api::read_competency($params['competencyid']);
4151          $scale = $competency->get_scale();
4152          $exporter = new evidence_exporter($evidence, array(
4153              'actionuser' => $USER,
4154              'scale' => $scale,
4155              'usercompetency' => null,
4156              'usercompetencyplan' => null,
4157              'context' => $evidence->get_context(),
4158          ));
4159          return $exporter->export($output);
4160      }
4161  
4162      /**
4163       * Returns description of grade_competency_in_course() result value.
4164       *
4165       * @return \external_value
4166       */
4167      public static function grade_competency_in_course_returns() {
4168          return evidence_exporter::get_read_structure();
4169      }
4170  
4171      /**
4172       * Returns description of unlink_plan_from_template_() parameters.
4173       *
4174       * @return \external_function_parameters
4175       */
4176      public static function unlink_plan_from_template_parameters() {
4177          $planid = new external_value(
4178              PARAM_INT,
4179              'Data base record id for the plan',
4180              VALUE_REQUIRED
4181          );
4182  
4183          $params = array(
4184              'planid' => $planid,
4185          );
4186          return new external_function_parameters($params);
4187      }
4188  
4189      /**
4190       * Unlink the plan from the template.
4191       *
4192       * @param int $planid The plan id
4193       * @return bool
4194       */
4195      public static function unlink_plan_from_template($planid) {
4196          $params = self::validate_parameters(self::unlink_plan_from_template_parameters(), array(
4197              'planid' => $planid,
4198          ));
4199  
4200          $plan = new plan($params['planid']);
4201          self::validate_context($plan->get_context());
4202  
4203          return api::unlink_plan_from_template($plan);
4204      }
4205  
4206      /**
4207       * Returns description of unlink_plan_from_template_() result value.
4208       *
4209       * @return \external_value
4210       */
4211      public static function unlink_plan_from_template_returns() {
4212          return new external_value(PARAM_BOOL, 'True if the unlink was successful');
4213      }
4214  
4215      /**
4216       * Returns description of template_viewed() parameters.
4217       *
4218       * @return \external_function_parameters
4219       */
4220      public static function template_viewed_parameters() {
4221          $id = new external_value(
4222              PARAM_INT,
4223              'Data base record id for the template',
4224              VALUE_REQUIRED
4225          );
4226  
4227          $params = array(
4228              'id' => $id,
4229          );
4230          return new external_function_parameters($params);
4231      }
4232  
4233      /**
4234       * Log the template viewed event.
4235       *
4236       * @param int $id the template id
4237       * @return array of warnings and status result
4238       * @throws moodle_exception
4239       */
4240      public static function template_viewed($id) {
4241          $params = self::validate_parameters(self::view_book_parameters(), array(
4242              'id' => $id
4243          ));
4244  
4245          $template = api::read_template($params['id']);
4246          self::validate_context($template->get_context());
4247  
4248          return api::template_viewed($params['id']);
4249      }
4250  
4251      /**
4252       * Returns description of template_viewed() result value.
4253       *
4254       * @return \external_value
4255       */
4256      public static function template_viewed_returns() {
4257          return new external_value(PARAM_BOOL, 'True if the log of the view was successful');
4258      }
4259  
4260      /**
4261       * Returns description of update_course_competency_settings() parameters.
4262       *
4263       * @return \external_function_parameters
4264       */
4265      public static function update_course_competency_settings_parameters() {
4266          $courseid = new external_value(
4267              PARAM_INT,
4268              'Course id for the course to update',
4269              VALUE_REQUIRED
4270          );
4271          $pushratingstouserplans = new external_value(
4272              PARAM_BOOL,
4273              'New value of the setting',
4274              VALUE_REQUIRED
4275          );
4276          $settings = new external_single_structure(array(
4277              'pushratingstouserplans' => $pushratingstouserplans
4278          ));
4279          $params = array(
4280              'courseid' => $courseid,
4281              'settings' => $settings,
4282          );
4283          return new external_function_parameters($params);
4284      }
4285  
4286      /**
4287       * Update the course competency settings
4288       *
4289       * @param int $courseid the course id
4290       * @param stdClass $settings The list of settings (currently only pushratingstouserplans).
4291       * @throws moodle_exception
4292       */
4293      public static function update_course_competency_settings($courseid, $settings) {
4294          $params = self::validate_parameters(self::update_course_competency_settings_parameters(), array(
4295              'courseid' => $courseid,
4296              'settings' => $settings
4297          ));
4298  
4299          $context = context_course::instance($params['courseid']);
4300          self::validate_context($context);
4301          $result = api::update_course_competency_settings($params['courseid'], $params['settings']);
4302  
4303          return $result;
4304      }
4305  
4306      /**
4307       * Returns description of update_course_competency_settings() result value.
4308       *
4309       * @return \external_value
4310       */
4311      public static function update_course_competency_settings_returns() {
4312          return new external_value(PARAM_BOOL, 'True if the update was successful.');
4313      }
4314  
4315      /**
4316       * Returns description of external function parameters.
4317       *
4318       * @return \external_function_parameters
4319       */
4320      public static function delete_evidence_parameters() {
4321          return new external_function_parameters(array(
4322              'id' => new external_value(PARAM_INT, 'The evidence ID'),
4323          ));
4324      }
4325  
4326      /**
4327       * External function delete_evidence.
4328       *
4329       * @param int $id The evidence ID.
4330       * @return boolean
4331       */
4332      public static function delete_evidence($id) {
4333          $params = self::validate_parameters(self::delete_evidence_parameters(), array(
4334              'id' => $id
4335          ));
4336  
4337          $evidence = api::read_evidence($params['id']);
4338          $uc = api::get_user_competency_by_id($evidence->get('usercompetencyid'));
4339          self::validate_context($uc->get_context());
4340  
4341          return api::delete_evidence($evidence);
4342      }
4343  
4344      /**
4345       * Returns description of external function result value.
4346       *
4347       * @return \external_function_parameters
4348       */
4349      public static function delete_evidence_returns() {
4350          return new external_value(PARAM_BOOL, 'The success');
4351      }
4352  
4353  }