Web services API - Function List

Following some old suggestion. I'll integrate them in the page with the time.

add_users

I think we should require all data needed for a successful "first login" to Moodle without popping him out the profile page to fill in all missing required data. This may require extra inputs such as city, description ... (unsure of the full list depending of Moodle version ?). Also password should be "required" if authentication method is "internal" .

INPUT: one or more of these in an array

   firstname
   lastname
   email 
   idnumber
   login 
   authentication method (optional , default= manual ?)

OPERATION:

   Adds one or more new users to the user database

OUTPUT:

   array of ids or false

delete_users

INPUT:

   String: field name ('id' or 'idnumber' or 'email' or 'login')
   Array: values

OPERATION:

   User is marked as deleted
   All it's role assignments are destroyed

OUTPUT:

   true/false

To Be Defined:

Security: avoid devastating calls such as delete_users ('confirmed',array(1)) or delete_users('firstname',array('patrick')). Where to implement it?
Wildcards: such as delete_users (array('idnumber','CS%'). Permit or not?

get_users

INPUT: one or more of these

   idnumber  or 
   email or 
   id or
   login

OPERATION:

   user record with optional fields set (Moodle 1.8 and later) and maybe some fields filtered out (password, 
   email if user said not to disclose it ...) depending of the identity of the "caller" (admin or the user himself)

OUTPUT:

   false  or user record

add_courses

INPUT: one or more of these in an array

   name
   shortname
   format (default topics)
   idnumber

OPERATION:

   Adds a new course to the course table

OUTPUT:

   id or false

delete_courses

INPUT: one or more of these in an array

   name OR
   shortname  OR
   idnumber OR
   id

OPERATION:

   Deletes courses from the course table
   What about associated ressources, roles ...

OUTPUT:

   true or false

get_courses

INPUT: one or more of these in an array

   id or  idnumber or shortname

OPERATION:

    fetch course record with some fields filtered out depending of the "caller" identity (admin, teacher, student ...)

OUTPUT:

   false  or course records in an array

Doubts: so id , idenumber or shortname stands for... user, category, the very course you want to get itself?

add_enrolments

INPUT:

  course unique Id (Moodle's ID or idnumber or shortname)     (could be one or an array)
  user unique id (Moodle's ID or idnumber or login or email)   (could be one or an array)
  role id (id or shortname or legacy capability name)   (could be one or an array)

OPERATION:

  assign given user a given role to given course

OUTPUT:

   true or false

delete_enrolments

INPUT:

  course unique Id (Moodle's ID or idnumber or shortname)    (could be one or an array)
  user unique id (Moodle's ID or idnumber or login or email)   (could be one or an array)
  role id (teacher, non editing teacher, student (?) ...)    (could be one or an array)

OPERATION:

  remove given user's "standard" role from given course

OUTPUT:

   true or false

get_enrolments

INPUT:

  user unique id (Moodle's ID or idnumber or login or email)
  context course or site

OPERATION:

  return a "list" of course's id in which given user move given user has some role assigned     
  return all the roles for a given courseid

OUTPUT:

   "array" of (course id, course shortname, course fullname, role id, role name, course url)
   or false in case of error (bad user id)

get_recent_activity

INPUT:

  user unique id (Moodle's ID or idnumber or login or email)
  course unique Id (Moodle's ID ,idnumber or shortname) - optional (default = all my courses)
  timestamp - optional (default = time of last connexion in every course)

OPERATION:

  return a "list" of changes (resource added/modified, new activities, etc.) for courses in which given user has some role assigned - since timestamp or last connexion in given course

OUTPUT:

   "array" of (course id, course shortname, course fullname, role id, role name, url of the resource/activity, time of change)
   or false in case of error (bad user/course id)

get_grades

(see grade_get_course_grade in grade/querylib.php)

INPUT:

  user unique id (Moodle's ID or idnumber or login or email)
  course unique Id (Moodle's ID ,idnumber or shortname) - optional (default = all my courses)

OPERATION:

  return a "list" of grades and statistics for the given student in the given course

OUTPUT:

   "array" of grades records (name,maxgrade,grade,percent,weight,weighted,sortOrder) 
   and "array" of stats (gradeItems,allgrades, points,totalpoints, percent, weight, weighted;)  
   or false in case of error (bad user/course id or user not in course)

get_groups

OPERATION:

  return a "list" of group records in a given course (or site ?)

add_groups

delete_groups

get_group_members

OPERATION:

  return a "list" of ids  for members of a group (within a course or global)

add_group_members

OPERATION:

  add new members to a group

delete_group_members

OPERATION:

  remove membership from a group

add_calendar_events

OPERATION:

  add/modify an event in Moodle database (site, course, private ...)

delete_calendar_events

OPERATION:

  delete given events

get_calendar_events

OPERATION:

  return in an "exportable" format (iCal, vCal ...)an event recorded in Moodle database (site, course, private ...)

admin

This API is used to change Moodle configuration variables. ...

///config values set_admin_config($configs) //$configs is array("config" => array("value","description","code")) get_admin_config($code) get_admin_configs()

///Plugins > Activities get_activity_module_config(...) set_activity_module_config(...) get_activity_modules(...)

///Plugins > Block ...

///Plugins > Filter ...

///Plugins > Portfolio ...

///Plugins > Repository get_repository_plugins(...) add_repository_plugins(...) remove_repository_plugins(...) get_repository_plugin_config(...) set_repository_plugin_config(...) get_repository_instances(...) add_repository_instances(...) remove_repository_instances(...) get_repository_instance_config(...) set_repository_instance_config(...)

///Security get_security_config($pagename=) //return array("pagename" => array("config"=>"value"))

                                 //usefull if you want retrieve all config in once for only for security

///Server
get_environment($version=null)
get_server_config($pagename=) //return array("pagename" => array("config"=>"value"))

...

blocks

blog

get_blog_entries($userid, $startdate, $enddate, $number) create_blog_entries($userid, $entries) //array of entry array delete_blog_entries($entryids) update_blog_entry($entry) get_blog_user_preferences($userid) //return array of config (array("configname","value")) set_blog_user_preferences($userid, $configs)

calendar

create_calendar_events(...) delete_calendar_events(...) get_calendar_events(...) //return in an "exportable" format (iCal, vCal ...)an event recorded in Moodle database (site, course, private ...)

course

create_courses($arrayCourses) create_course_enrolments($role,$criteria_course,$course,$criteria_user,$users) delete_courses($criteria, $arrayCourses) delete_course_enrolments($role,$criteria_course,$course,$criteria_user,$users) get_courses($criteria, $arraySearch) get_course_enrolments($criteria_user,$user) get_courses_recent_activities($criteria, $arrayCourses)

get_course_activities($courseid=0, $groupid=null) // return the list of activity {id, name, type} get_course_resources($courseid=0, $groupid=null) // return the list of {id,. resource, type} create_section() get_sections() delete_section() get_metacourse()

Course Format

get_course_outline($courseid=0, $groupid=null) // to discuss, maybe xml stuff

get_course_outline would be a nice to have from the webservices consumer app. If an external app needs to render the moodle course, need's more than just activities and resources, it needs to know how to display it. this function whould be implemented by the course format.

TODO: define course outline xml dtd

grade

get_grades(...)

group

add_group_members($criteriaCourse, $course, $criteriaUser, $arrayUsers, $groupname) create_groups($criteria, $course, $groupnames) delete_groups($criteria, $course, $groupnames) get_groups($criteria, $course) get_groups_by_course($courseid) get_group_members($criteria, $course, $groupname) remove_group_members($criteriaCourse, $course, $criteriaUser, $arrayUsers, $groupname) set_group(...) update_group(...)

create_grouping() delete_grouping() update_grouping() get_grouping() add_group_to_grouping() get_groups_from_grouping() delete_group_from_grouping()

mod

assignment

chat

choice

data

feedback

forum

get_forums_by_courses($courseids) get_forums_discussions($discussions=null, $forumids=null, $courseids) //you can retrieve discussions by id

                                                                     //and/or by forums and/or by courses

get_forums_posts_by_discussions($discussionids) get_forums_posts($postids) set_forum_posts($posts) update_forum_posts($posts) create_forum_posts($discussionid, $posts) create_forum_discussiosn($courseid, $discussions) set_forum_discussions($discussions) update_forum_discussions($discussions) delete_forum_discussions($discussions) delete_forum_posts($posts) search_forum_string($stringtosearch, $forumids=null, $discussionids=null)

glossary

lesson

quiz

resource

scorm

survey

wiki

portfolio

repository

///functions to let teacher and user manage their repositories get_repository_instances($repository_type=null, $userid=null, $courseid=null) //if courseid!=null, get course level instances,

                                                                             //else if userid != null get user level instances

add_repository_instances($repositoryinstances) remove_repository_instances($repositoryinstances) get_repository_instance_config($repositoryinstanceid) set_repository_instance_config($repositoryinstanceid,$configs)

Role

create_role()
get_roles()
update_role()
delete_role()
assign_role()
inherit_capability()
allow_capability()
prevent_capability()
prohibit_capability()
get_users_by_role()
has_capability()

search

search($string);

tag

user

create_users($users) //$users is an array of $user

                               //$user is an array(username, password, forcechangepwd, firstname, 
                               //                  lastname, email, emaildisplay, emailactivated,
                               //                  city, country, timezone, language, description,...)

delete_users($criteria, $users) get_users($criteria, $users) set_user($user) //$user is an array(...) update_user($user) //$user is an array(...)

Documentation

Web services API - Function List

add_users

delete_users

get_users

add_courses

delete_courses

get_courses

add_enrolments

delete_enrolments

get_enrolments

get_recent_activity

get_grades

get_groups

add_groups

delete_groups

get_group_members

add_group_members

delete_group_members

add_calendar_events

delete_calendar_events

get_calendar_events

admin

blocks

blog

calendar

Category

course

Course Format

grade

group

mod

assignment

chat

choice

data

feedback

forum

glossary

lesson

quiz

resource

scorm

survey

wiki

portfolio

repository

Role

search

tag

user