MDL-50353 scorm: New Web Service mod_scorm_insert_scorm_tracks
authorJuan Leyva <juanleyvadelgado@gmail.com>
Wed, 10 Jun 2015 11:15:42 +0000 (13:15 +0200)
committerJuan Leyva <juanleyvadelgado@gmail.com>
Wed, 16 Sep 2015 20:07:34 +0000 (22:07 +0200)
lib/db/services.php
mod/scorm/classes/external.php
mod/scorm/db/services.php
mod/scorm/tests/externallib_test.php

index 538d945..a1a9853 100644 (file)
@@ -1209,6 +1209,7 @@ $services = array(
             'mod_scorm_view_scorm',
             'mod_scorm_get_scorm_scoes',
             'mod_scorm_get_scorm_user_data',
+            'mod_scorm_insert_scorm_tracks',
             'mod_scorm_get_scorm_attempt_count',
             'mod_page_view_page',
             'mod_resource_view_resource',
index 03bbe17..cb0d1c1 100644 (file)
@@ -389,4 +389,105 @@ class mod_scorm_external extends external_api {
             )
         );
     }
+
+    /**
+     * Describes the parameters for insert_scorm_tracks.
+     *
+     * @return external_function_parameters
+     * @since Moodle 3.0
+     */
+    public static function insert_scorm_tracks_parameters() {
+        return new external_function_parameters(
+            array(
+                'scoid' => new external_value(PARAM_INT, 'SCO id'),
+                'attempt' => new external_value(PARAM_INT, 'attempt number'),
+                'tracks' => new external_multiple_structure(
+                    new external_single_structure(
+                        array(
+                            'element' => new external_value(PARAM_RAW, 'element name'),
+                            'value' => new external_value(PARAM_RAW, 'element value')
+                        )
+                    )
+                ),
+            )
+        );
+    }
+
+    /**
+     * Saves a SCORM tracking record.
+     * It will overwrite any existing tracking data for this attempt.
+     * Validation should be performed before running the function to ensure the user will not lose any existing attempt data.
+     *
+     * @param int $scoid the SCO id
+     * @param string $attempt the attempt number
+     * @param array $tracks the track records to be stored
+     * @return array warnings and the scoes data
+     * @throws moodle_exception
+     * @since Moodle 3.0
+     */
+    public static function insert_scorm_tracks($scoid, $attempt, $tracks) {
+        global $USER, $DB;
+
+        $params = self::validate_parameters(self::insert_scorm_tracks_parameters(),
+                                            array('scoid' => $scoid, 'attempt' => $attempt, 'tracks' => $tracks));
+
+        $trackids = array();
+        $warnings = array();
+
+        $sco = scorm_get_sco($params['scoid'], SCO_ONLY);
+        if (!$sco) {
+            throw new moodle_exception('cannotfindsco', 'scorm');
+        }
+
+        $scorm = $DB->get_record('scorm', array('id' => $sco->scorm), '*', MUST_EXIST);
+        $cm = get_coursemodule_from_instance('scorm', $scorm->id);
+
+        $context = context_module::instance($cm->id);
+        self::validate_context($context);
+
+        // Check settings / permissions to view the SCORM.
+        require_capability('mod/scorm:savetrack', $context);
+
+        // Check settings / permissions to view the SCORM.
+        scorm_require_available($scorm);
+
+        foreach ($params['tracks'] as $track) {
+            $element = $track['element'];
+            $value = $track['value'];
+            $trackid = scorm_insert_track($USER->id, $scorm->id, $sco->id, $params['attempt'], $element, $value,
+                                            $scorm->forcecompleted);
+
+            if ($trackid) {
+                $trackids[] = $trackid;
+            } else {
+                $warnings[] = array(
+                    'item' => 'scorm',
+                    'itemid' => $scorm->id,
+                    'warningcode' => 1,
+                    'message' => 'Element: ' . $element . ' was not saved'
+                );
+            }
+        }
+
+        $result = array();
+        $result['trackids'] = $trackids;
+        $result['warnings'] = $warnings;
+        return $result;
+    }
+
+    /**
+     * Describes the insert_scorm_tracks return value.
+     *
+     * @return external_single_structure
+     * @since Moodle 3.0
+     */
+    public static function insert_scorm_tracks_returns() {
+
+        return new external_single_structure(
+            array(
+                'trackids' => new external_multiple_structure(new external_value(PARAM_INT, 'track id')),
+                'warnings' => new external_warnings(),
+            )
+        );
+    }
 }
index 540518a..9d3b054 100644 (file)
@@ -57,4 +57,15 @@ $functions = array(
         'type' => 'read',
         'capabilities' => ''
     ),
+
+    'mod_scorm_insert_scorm_tracks' => array(
+        'classname' => 'mod_scorm_external',
+        'methodname' => 'insert_scorm_tracks',
+        'description' => 'Saves a scorm tracking record.
+                          It will overwrite any existing tracking data for this attempt.
+                          Validation should be performed before running the function to ensure the user will not lose any existing
+                          attempt data.',
+        'type' => 'write',
+        'capabilities' => 'mod/scorm:savetrack'
+    ),
 );
index 7bc9f8a..a0cf4a8 100644 (file)
@@ -347,4 +347,89 @@ class mod_scorm_external_testcase extends externallib_advanced_testcase {
             $this->assertEquals('invalidrecord', $e->errorcode);
         }
     }
+
+    /**
+     * Test insert scorm tracks
+     */
+    public function test_mod_scorm_insert_scorm_tracks() {
+        global $DB;
+
+        $this->resetAfterTest(true);
+
+        // Create users.
+        $student = self::getDataGenerator()->create_user();
+
+        // Set to the student user.
+        self::setUser($student);
+
+        // Create courses to add the modules.
+        $course = self::getDataGenerator()->create_course();
+
+        // First scorm, dates restriction.
+        $record = new stdClass();
+        $record->course = $course->id;
+        $record->timeopen = time() + DAYSECS;
+        $record->timeclose = $record->timeopen + DAYSECS;
+        $scorm = self::getDataGenerator()->create_module('scorm', $record);
+
+        // Get a SCO.
+        $scoes = scorm_get_scoes($scorm->id);
+        $sco = array_shift($scoes);
+
+        // Tracks.
+        $tracks = array();
+        $tracks[] = array(
+            'element' => 'cmi.core.lesson_status',
+            'value' => 'completed'
+        );
+        $tracks[] = array(
+            'element' => 'cmi.core.score.raw',
+            'value' => '80'
+        );
+
+        // Users enrolments.
+        $studentrole = $DB->get_record('role', array('shortname' => 'student'));
+        $this->getDataGenerator()->enrol_user($student->id, $course->id, $studentrole->id, 'manual');
+
+        // Exceptions first.
+        try {
+            mod_scorm_external::insert_scorm_tracks($sco->id, 1, $tracks);
+            $this->fail('Exception expected due to dates');
+        } catch (moodle_exception $e) {
+            $this->assertEquals('notopenyet', $e->errorcode);
+        }
+
+        $scorm->timeopen = time() - DAYSECS;
+        $scorm->timeclose = time() - HOURSECS;
+        $DB->update_record('scorm', $scorm);
+
+        try {
+            mod_scorm_external::insert_scorm_tracks($sco->id, 1, $tracks);
+            $this->fail('Exception expected due to dates');
+        } catch (moodle_exception $e) {
+            $this->assertEquals('expired', $e->errorcode);
+        }
+
+        // Test invalid instance id.
+        try {
+             mod_scorm_external::insert_scorm_tracks(0, 1, $tracks);
+            $this->fail('Exception expected due to invalid sco id.');
+        } catch (moodle_exception $e) {
+            $this->assertEquals('cannotfindsco', $e->errorcode);
+        }
+
+        $scorm->timeopen = 0;
+        $scorm->timeclose = 0;
+        $DB->update_record('scorm', $scorm);
+
+        // Retrieve my tracks.
+        $result = mod_scorm_external::insert_scorm_tracks($sco->id, 1, $tracks);
+        $result = external_api::clean_returnvalue(mod_scorm_external::insert_scorm_tracks_returns(), $result);
+        $this->assertCount(0, $result['warnings']);
+
+        $trackids = $DB->get_records('scorm_scoes_track', array('userid' => $student->id, 'scoid' => $sco->id,
+                                                                'scormid' => $scorm->id, 'attempt' => 1));
+
+        $this->assertEquals(array_keys($trackids), $result['trackids']);
+    }
 }