Uploaded image for project: 'Moodle'
  1. Moodle
  2. MDL-48412

Cohort Webservices inconsistently use idnumber

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Open
    • Priority: Minor
    • Resolution: Unresolved
    • Affects Version/s: 2.8.1
    • Fix Version/s: None
    • Component/s: Cohorts, Web Services
    • Labels:
    • Testing Instructions:
      Hide

      Enable moodle webservices by following the instructions here:
      http://example.com/admin/settings.php?section=webservicesoverview

      on Step 4, ensure that the user has the capabilities: "Create, delete and move cohorts", and "Add and remove cohort members"

      On step 2: Use whichever protocol you are familiar with. I used REST and will use it for these steps.

      On step 6, add the seven cohort webservice functions, then continue with the steps.

      Once completed, use your favorite webservice testing tool (I used google chrome's "Advanced REST Service Client") and compose some service content tests.

      for these tests, the service url pattern is:
      http://example.com/webservice/rest/server.php?moodlewsrestformat=json&wstoken=[[servicetoken]]&wsfunction=[[service_function]]&[[extras]]

      where:
      [[servicetoken]]= the token you got in step 8 above
      [[service_function]] = one of the seven functions you are testing
      [[extras]] the url formatted variables to pass to the service

      Test 1) create a cohort with a remote id (the idnumber field)
      service_function: core_cohort_create_cohorts
      extras:
      cohorts[0][categorytype][type]= string
      cohorts[0][categorytype][value]= string
      cohorts[0][name]= "External Cohort number 1"
      cohorts[0][idnumber]= "cohort_ext_0001"
      cohorts[0][description]= "this is an external cohort"
      cohorts[0][descriptionformat]= 1
      cohorts[0][visible]= 1

      expected result:
      http status: 200

      Test 2) look up the cohort you just created using the get_cohorts function:
      service_function: core_cohorts_get_cohorts
      extras:
      cohortsids[0]='cohort_ext_0001'
      type='idnumber'

      expected result:
      http status 200 with json version of cohort.

      Test 3: Add a member to the cohort using the idnumber and user id.
      service_function: core_cohort_add_cohort_members
      extras:
      members[0][cohorttype][type]= 'idnumber'
      members[0][cohorttype][value]= 'cohort_ext_0001'
      members[0][usertype][type]= 'id'
      members[0][usertype][value]= 1

      expected result:
      http status: 200

      test 4) remove the cohort member using cohort id number and user id:
      service function: core_cohort_delete_cohort_members
      extras:
      members[0][cohortid]= 'cohort_ext_0001'
      members[0][userid]= '1'
      type='idnumber'

      Test #5: Delete a cohort using the idnumber field:
      service_function: core_cohort_delete_cohort
      extras:
      cohortids[0]= 'cohort_ext_0001'
      type='idnumber'

      The end.

      Show
      Enable moodle webservices by following the instructions here: http://example.com/admin/settings.php?section=webservicesoverview on Step 4, ensure that the user has the capabilities: "Create, delete and move cohorts", and "Add and remove cohort members" On step 2: Use whichever protocol you are familiar with. I used REST and will use it for these steps. On step 6, add the seven cohort webservice functions, then continue with the steps. Once completed, use your favorite webservice testing tool (I used google chrome's "Advanced REST Service Client") and compose some service content tests. for these tests, the service url pattern is: http://example.com/webservice/rest/server.php?moodlewsrestformat=json&wstoken=[[servicetoken]]&wsfunction=[[service_function]]&[[extras ]] where: [ [servicetoken] ]= the token you got in step 8 above [ [service_function] ] = one of the seven functions you are testing [ [extras] ] the url formatted variables to pass to the service Test 1) create a cohort with a remote id (the idnumber field) service_function: core_cohort_create_cohorts extras: cohorts [0] [categorytype] [type] = string cohorts [0] [categorytype] [value] = string cohorts [0] [name] = "External Cohort number 1" cohorts [0] [idnumber] = "cohort_ext_0001" cohorts [0] [description] = "this is an external cohort" cohorts [0] [descriptionformat] = 1 cohorts [0] [visible] = 1 expected result: http status: 200 Test 2) look up the cohort you just created using the get_cohorts function: service_function: core_cohorts_get_cohorts extras: cohortsids [0] ='cohort_ext_0001' type='idnumber' expected result: http status 200 with json version of cohort. Test 3: Add a member to the cohort using the idnumber and user id. service_function: core_cohort_add_cohort_members extras: members [0] [cohorttype] [type] = 'idnumber' members [0] [cohorttype] [value] = 'cohort_ext_0001' members [0] [usertype] [type] = 'id' members [0] [usertype] [value] = 1 expected result: http status: 200 test 4) remove the cohort member using cohort id number and user id: service function: core_cohort_delete_cohort_members extras: members [0] [cohortid] = 'cohort_ext_0001' members [0] [userid] = '1' type='idnumber' Test #5: Delete a cohort using the idnumber field: service_function: core_cohort_delete_cohort extras: cohortids [0] = 'cohort_ext_0001' type='idnumber' The end.
    • Affected Branches:
      MOODLE_28_STABLE
    • Pull from Repository:

      Description

      ISSUE:
      The cohort webservice functions allow for the creation of cohorts that include values for the external idnumber field, but they inconsistently allow for the lookup of cohorts and cohort_members based on the idnumber value. This should be uniformly supported across the cohort functions. This will allow external systems to create and populate cohorts consistently without both systems needing to know and store the id/idnumber pairs.

      SUMMARY:
      There are 7 cohorts webservices:
      core_cohort_get_cohorts,
      core_cohort_create_cohorts,
      core_cohort_delete_cohorts,
      core_cohort_update_cohorts,
      core_cohort_add_cohort_members,
      core_cohort_delete_cohort_members,
      core_cohort_get_cohort_members

      Of these only a few support the use of the IDNUMBER field associated cohorts and users. Some allow for lookup based on ID or IDNUMBER, some allow ID and USERNAME (in the case of core_cohort_get_cohort_members, and core_cohort_add_cohort_members) and others only allow by ID.

      Considering that external systems must create their own cohorts into moodle (or provide admins with the capability of applying a specific cohortid to a related object), and the fact that some service functions allow for the passing of IDNUMBER, it would make sense if this was handled in a more unified fashion across the services.

      FIX:
      I've introduced an optional field called "type" that can be used to tell the service what kind of ID field the id value is a reference to. This has been added to all of the services in an applicable spot (this is either with the ID/IDNUMBER, or as second argument passed in to the service. The precedence for this is set with core_cohort_create_cohort's category['type'] and the core_cohort_add_cohort_members cohorttype['type'] and usertype['type'].

      I know that according to the Webservice API documentation, altering the API is a very taboo thing to do. Keeping this in mind, I made sure that all functions work as-is, thus preserving existing calls to the webservice. The type requirement for the ID fields of some of the services changed to be more relaxed, and the service functions handle that correctly.

      FUTURE STEPS:
      There are some things that should be modified during an API breaking cycle, but these are not included here. The two major such suggestions would be 1) to change core_cohort_get_cohorts to be a listing engine that does not require existing knowledge of ID's, and 2) to change how all ID fields are handled to consistently be value/type pairs (as how core_cohort_add_cohort_members currently handles id's) rather than stand alone values (as how core_cohort_delete_cohort_members handles id's).

      CODE TO REVIEW:
      https://github.com/netw3rker/moodle/compare/moodle:MOODLE_28_STABLE...cohort_webservice_idnumber_support

        Attachments

          Issue Links

            Activity

              People

              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated: