Conduit includes web service endpoints for messages to do most all of the things that can be done in the user interface and through files. Conduit’s web services include the record action calls (create, update, and delete actions) for the record types in Conduit as well as some methods for retrieving data for use in external systems (SIS or student portals). The handle methods provide actions with identical coverage for records that you have in the flat files and uses the same mappings and rules in Conduit. The GET methods provide access to grades, course information, and student information from remote systems. There are also core Moodle™ APIs available for use for records and information; these are not covered in this article.
For more information on Core APIs please visit the web services tab in your site administration menu. All core APIs are listed in that documentation. Warning! The Core API list is over 1600 pages in length as a PDF; it may take some time to load and to export.
The Conduit action or record management calls support create, update, and delete actions for users, courses, enrollments, roles (separate from an enrollment), groups (creation in a course), and group memberships (in those course level groups). There is also support for Cohort (system-wide groups) management in Conduit.
When testing and developing, it is nice to use a tool to send the POST messages at the endpoints and capture the results. I use a tool called Boomerang; a Chrome extension that can send POSTs and show results. Note: The example calls are using invalid information and will fail if run as they are written. Please use the example as a template and substitute your test site URL, key, and record details.
Getting set up
To start you’ll need to check the configuration in Conduit on the site you are using. In the Conduit block, head to the Settings and switch to the Web services tab. The page has some settings details to start. You will also see a listing of the endpoints for the site. You’ll need those for your web service calls; note that there are separate endpoints for each data object type; users, courses, enrollments, etc.
Securing the transactions
Set up a Token if there isn’t one already; grab the token for use in the calls once it has been set. This token is the authentication for the transactions. Every POST will pass this token and it must match in order for Conduit to accept the rest of the message. Be sure to set the mode to use HTTPS; you should never send transactions over unsecured protocols. You can restrict the traffic to a specific IP Address or range to prevent outside tools or actors from trying to send messages to your site’s Conduit endpoints. Important for production use, but could be left open for testing purposes.
Grades settings
The Web services settings page also includes settings for managing what kinds of responses for requests for grades are supported. This allows you to define the defaults for GET method requests for grades. Settings cover if deleted grades are included or excluded and what kinds of grade items are available in the response. Possible grade items available are Course, Module (individual activity), Manual (Grade items added directly to the gradebook), and Category grades.
Deleted grades can increase the payload with deleted entries and increase the time to process. The system Grade History settings will impact the availability of previously deleted grade items based on how long those histories are allowed to store them. Typically deleted items are not needed so they are left out of the response.
If a gradebook has 35 graded items and 5 categories, a request for a user’s course grades with Modules, Categories, and Course grades will return 41 results for the one user in one course.
Data mapping
The web service calls use a data structure that is the same as the data mappings set in Conduit’s configuration. If the site is already using data in flat files, the data mapping should be the same for both the web service and the flat file. Once the Mappings are configured in Conduit, you can use the XML schema button for each record type in the Mappings table to get an example of that record’s structure. This is a convenient way to jumpstart your testing.
In the Settings page, Mappings are defined to build out the relationship between inbound data and the record fields in Open LMS. For example, Conduit could be configured to map the inbound uid field from the external source to the idnumber in the user record in Open LMS. The easiest way to start loading data is to first review the data about the users that you have and determine which need to be in the user record in Open LMS.
If there is a field that we have data for in the external source that should be in the user record, we create a mapping for that data in the Conduit Mappings table. Every field in the user record has an available mapping in the interface, including fields that have been created as custom profile fields. Not all fields need to be mapped and inbound records can provide fewer fields than the mapping contains. If an inbound record contains extra fields that are not in the mapping, these will be ignored and create a warning in the transaction record.
Message structure
POSTs are structured with a pointer to the endpoint in use, the token that authenticates the message as valid, the method in use (handle or a specific get method), and the xml package. A POST might look like this:
https://mysiteurl.openlms/blocks/conduit/webservices/rest/user.php?token=TOKEN&method=handle&xml=<?xml version=’1.0’?><data><datum action=”update”> <mapping name=”mappedname1”>VALUE1</mapping> <mapping name=”mappedname2”>VALUE2</mapping> </datum> </data>
The target: https://mysiteurl.openlms/blocks/conduit/webservices/rest/user.php
The token: token=TOKEN
The method: method=handle or method=get_user_grades or other GET method. Handle covers all the actions and the specific action is defined in the datum action value for each datum passed. A package with the method=handle could include records that are created, updated, and deleted; with each datum specifying the particular action that it carries.
The xml package: xml= … The specifics of the package vary with the configuration of the data being sent or the specific GET method in use. The possible structure for each data type for a handle transaction is specified in the mappings for that data type.
For example, a possible structure for a create enrollment action would be:
<?xml version="1.0" encoding="UTF-8"?>
<data>
<datum action="create">
<mapping name="course">course_id</mapping>
<mapping name="user">user_id</mapping>
<mapping name="role">rolename</mapping>
</datum>
</data>
The exact elements in use and the names of the mapped fields are dependent on the mappings on your site’s Conduit. The values sent will be the ones you need to have in the record. However, the overall structure of the package will match this. Keep in mind that not every mapped field must be included, just those that are required to make a record that works.
Required fields
Required fields are indicated in the Mappings page in Conduit. For reference here are the required fields for each record type.
User:
The key record value as defined in the General Settings in Conduit. Either username, email address, or idnumber. In practice, user records will always need a username, an email value, a firstname, a lastname, and a city/town value.
Course:
The key record value as defined in the General Settings in Conduit. Either shortname or idnumber. In practice, a course will require a shortname and a fullname.
Enrollment:
Enrollments require a coursekey and a userkey. In practice, enrollments also require a role. The role will be identified by the key record value as defined in the General Settings in Conduit. Either shortname or name.
Role assignments:
Roles do not need to be separated from enrollments typically. This functionality is for assignment of roles into unusual spaces like categories or specific content within a course. It is not advisable to use this for normal enrollments. Contact support or work with your configuration team to determine if this functionality is right for you.
Roles require a context, moodlekey, userkey, and rolekey to work. The context sets the context level in the system (category, course, content item) and the moodlekey is the internal record value for that context.
Groups:
Creating groups in a course requires a coursekey and a groupkey, which can then be used to identify the group when handling group enrollment actions.
Group members:
Group members can be enrolled once groups have been created. This requires a coursekey, a userkey, and a groupkey.
Cohort members:
Adding users into cohorts can be handled via Conduit. This requires a userkey and a cohortkey, which is the id number of the target cohort.
Methods Available by Endpoint
As noted, methods are either handles or GETs. Handles have the same actions available to them as the file transactions do for each type of record. GET methods are calls that allow you to programatically get information from Conduit about the state of the information in Open LMS. Many of the use cases for the GET methods are for creating external portals for users to present their grades or calendars outside of Open LMS.
User GET Methods
GET_USER
Return a specified user's profile information.
GET_USER_COURSE_RECENT_ACTIVITY
Return a listing of activities that have been added, updated, or deleted for a specified user.
GET_USER_COURSE_ACTIVITIES_DUE
Return a listing of the activities and their due dates assigned to the specified user.
GET_USER_COURSE_EVENTS
Return the course calendar events for a specific user. Please use the get_user_course_activities_due service to access activity due dates.
GET_USER_GRADES
Return a listing of grade items for the specified user. The possible items returned are set both by the parameters and the settings in Conduit. (Course grade vs item grade, etc.)
User Handle Actions
- create
- update
- delete
Course GET Methods
GET_COURSE
Return the course settings for the specified course.
GET_COURSE_GRADES
Return a listing of grade items for the specified course. The possible items returned are set both by the parameters and the settings in Conduit. (Course grade vs item grade, etc.)
Course Handle Actions
- create
- update
- delete
Enrollment Handle Actions
- create
- update
- delete
Role assignment Handle Actions
- create
- update
- delete
Groups GET Methods
GET_GROUPS
Return the settings for the specified group.
Groups Handle Actions
- create
- update
- delete
Group members Handle Actions
- create
- delete
Cohort members Handle Actions
- create
- delete
GET Method and Handle Details
The following is a detailed description of each of the GET methods available with their parameters and sample calls and responses. Included are examples of the handles for each endpoint. For complete details on available record fields, please review the Conduit Mappings documentation. The fields in use and their mapped names will vary based on your own configuration of the Conduit Mappings. The examples below are designed to show what the data structure might look like.
GET_USER
Get a user’s profile data including custom profile fields.
POST PARAMETERS:
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to get_user.
string value: (Required) The user value to lookup, such as the user’s name.
string field: (Optional, Default: username) The Moodle table field to look up against. Can be id, username, idnumber or email.
RETURNED XML SCHEMA
<?xml version=”1.0″ encoding=”UTF-8″?><Service_User generator=”zend” version=”1.0″>
<get_user>
<user>
<id>int</id>
<auth>string<auth>
<confirmed>int</confirmed>
<policyagreed>int</policyagreed>
<deleted>int</deleted>
<mnethostid>int</mnethostid>
<username>string</username>
<idnumber>string</idnumber>
<firstname>string</firstname>
<lastname>string</lastname>
<email>string</email>
<emailstop>int</emailstop>
<icq>string</icq>
<skype>string</skype>
<yahoo>string</yahoo>
<aim>string</aim>
<msn>string</msn>
<phone1>string</phone1>
<phone2>string</phone2>
<institution>string</institution>
<department>string</department>
<address>string</address>
<city>string</city>
<country>string</country>
<lang>string</lang>
<theme>string</theme>
<timezone>int</timezone>
<firstaccess>int</firstaccess>
<lastaccess>int</lastaccess>
<lastlogin>int</lastlogin>
<currentlogin>int</currentlogin>
<picture>int</picture>
<url>string</url>
<description>string</description>
<mailformat>int</mailformat>
<maildigest>int</maildigest>
<maildisplay>int</maildisplay>
<htmleditor>int</htmleditor>
<ajax>int</ajax>
<autosubscribe>int</autosubscribe>
<trackforums>int</trackforums>
<timemodified>int</timemodified>
<trustbitmask>int</trustbitmask>
<imagealt>string</imagealt>
<screenreader>int</screenreader>
</user>
<status>success</status>
</get_user></Service_User>
GET_USER_COURSE_RECENT_ACTIVITY
Provides an external interface to retrieve information about all activities that have been added, updated or deleted for a period of time within the courses a user is enrolled in.
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to get_user_course_recent_activity.
string username: (Required) The user’s user name.
string course: (Optional, Default: NULL) The course’s ID number – if not passed, all user courses are returned.
int fromdate: (Optional, Default: NULL) UNIX time stamp of the start date.
RETURNED XML FORMAT
<?xml version=”1.0″ encoding=”UTF-8″?><Service_User generator=”zend” version=”1.0″>
<get_user_course_recent_activity>
<courses>
<course>
<id>integer</id>
<fullname>string</fullname>
<shortname>string</shortname>
<idnumber>string</idnumber>
<url>string</url>
<visible>int</visible>
<activities>
<activity>
<id>integer</id>
<type>string</type>
<name>string</name>
<timestamp>integer(unixtimestamp)</timestamp>
<descriptionhtml>string(html)/descriptionhtml>
<descriptiontext>string</descriptiontext>
<url>string</url>
</activity>
</activities>
</course>
</courses>
<status>success/fail</status>
</get_user_course_recent_activity></Service_User>
EXAMPLE RETURN XML
<?xml version=”1.0″ encoding=”UTF-8″?><Service_User generator=”zend” version=”1.0″>
<get_user_course_recent_activity>
<courses>
<course>
<id>12088</id>
<fullname>Reporting Course</fullname>
<shortname>REPO</shortname>
<idnumber>IDNUM</idnumber>
<url>http://example.com/course/view.php?id=12088</url>
<visible>1</visible>
<activities>
<activity>
<id>6114</id>
<type>assignment</type>
<name>Not graded</name>
<timestamp>1245093524</timestamp>
<descriptionhtml>Added Assignment by Admin User:<a href=”http://example.com/mod/assignment/view.php?id=6114″></descriptionhtml>
<descriptiontext>Added Assignment by Admin User: Not graded</descriptiontext>
<url>http://example.com/mod/assignment/view.php?id=6114</url>
</activity>
<activity>
<id>6115</id>
<type>assignment</type>
<name>Graded</name>
<timestamp>1245093540</timestamp>
<descriptionhtml>Added Assignment by Admin User:<a href=”http://example.com/mod/assignment/view.php?id=6115></descriptionhtml>
<descriptiontext>Added Assignment by Admin User: Graded</descriptiontext>
<url>http://example.com/mod/assignment/view.php?id=6115</url>
</activity>
<activity>
<id>6116</id>
<type>quiz</type>
<name>Graded quiz</name>
<timestamp>1245093564</timestamp>
<descriptionhtml>Added Quiz by Admin User:<a href=”http://example.com/mod/quiz/view.php?id=6116″></descriptionhtml>
<descriptiontext>Added Quiz by Admin User: Graded quiz</descriptiontext>
<url>http://example.com/mod/quiz/view.php?id=6116</url>
</activity>
<activity>
<id>6117</id>
<type>quiz</type>
<name>Not graded quiz</name>
<timestamp>1245093655</timestamp>
<descriptionhtml>Added Quiz by Admin User:<a href=”http://example.com/mod/quiz/view.php?id=6117″></descriptionhtml>
<descriptiontext>Added Quiz by Admin User: Not graded quiz</descriptiontext>
<url>http://example.com/mod/quiz/view.php?id=6117</url>
</activity>
</activities>
</course>
</courses>
<status>success</status>
</get_user_course_recent_activity></Service_User>
GET_USER_COURSE_ACTIVITIES_DUE
Provides external access to the activities that a user has due in a course within a given time period.
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to get_user_course_activities_due.
string username: (Required) The user’s username.
int todate: (Required) Unix timestamp of the end date.
string course: (Optional, default = NULL) The course’s idnumber – if not passed, all user courses are returned.
RETURNED XML FORMAT
<?xml version=”1.0″ encoding=”UTF-8″?><Service_User generator=”zend” version=”1.0″>
<get_user_course_activities_due>
<courses>
<course>
<id>integer</id>
<fullname>string</fullname>
<shortname>string</shortname>
<idnumber>string</idnumber>
<url>string</url>
<activities>
<activity>
<id>integer</id>
<type>string</type>
<name>string</name>
<descriptionhtml>string(html)</descriptionhtml>
<descriptiontext>string</descriptiontext>
<duedate>integer(unixtimestamp)</duedate>
<url>string</url>
</activity>
</activities>
</course>
</courses>
<status>success/fail</status>
</get_user_course_activities_due></Service_User>
EXAMPLE RETURN XML
<?xml version=”1.0″ encoding=”UTF-8″?><Service_User generator=”zend” version=”1.0″>
<get_user_course_activities_due>
<courses>
<course>
<id>12088</id>
<fullname>Reporting Course</fullname>
<shortname>REPO</shortname>
<idnumber>IDNUM</idnumber>
<url>http://example.com/course/view.php?id=12088</url>
<activities>
<activity>
<id>7797</id>
<type>quiz</type>
<name>Another quiz</name>
<descriptionhtml><p>asdf </p></descriptionhtml>
<descriptiontext>asdf</descriptiontext>
<duedate>0</duedate>
<url>http://example.com/mod/quiz/view.php?id=7797</url>
</activity>
<activity>
<id>6114</id>
<type>assignment</type>
<name>Not graded</name>
<descriptionhtml><p> Descasdf</p></descriptionhtml>
<descriptiontext>Descasdf</descriptiontext>
<duedate>1277234100</duedate>
<url>http://example.com/mod/assignment/view.php?id=6114</url>
</activity>
<activity>
<id>9103</id>
<type>assignment</type>
<name>eFolio</name>
<descriptionhtml><p> Introduction </p></descriptionhtml>
<descriptiontext>Introduction</descriptiontext>
<duedate>1306360800</duedate>
<url>http://example.com/mod/assignment/view.php?id=9103</url>
</activity>
</activities>
</course>
</courses>
<status>success</status>
</get_user_course_activities_due></Service_User>
GET_USER_COURSE_EVENTS
Provides external access to the user’s course events within a course. Please use the get_user_course_activities_due service to access activity due dates.
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to get_user_course_events.
string username: (Required) The user’s user name.
int fromdate: (Required) UNIX timestamp of the start date.
int todate: (Required) UNIX timestamp of the end date.
string course: (Optional, Default: NULL ) The course’s ID number – if not passed, all user courses are returned.
RETURNED XML FORMAT
<div><code><?xml version=”1.0″ encoding=”UTF-8″?><Service_User generator=”zend” version=”1.0″>
<get_user_course_events>
<courses>
<course>
<id>integer</id>
<fullname>string</fullname>
<shortname>string</shortname>
<idnumber>string</idnumber>
<url>string</url>
<events>
<event>
<id>integer</id>
<name>string</name>
<timestart>integer(unix timestamp)</timestart>
<timeend>integer(unix timestamp)</timeend>
<description>string</description>
<url>string</url>
</event>
</events>
</course>
</courses>
<status>success</status>
</get_user_course_events></Service_User>
EXAMPLE RETURN XML
<?xml version=”1.0″ encoding=”UTF-8″?><Service_User generator=”zend” version=”1.0″>
<get_user_course_events>
<courses>
<course>
<id>12088</id>
<fullname>Reporting Course</fullname>
<shortname>REPO</shortname>
<idnumber>IDNUM</idnumber>
<url>http://example.com/course/view.php?id=12088</url>
<events>
<event>
<id>507</id>
<name>Event 1</name>
<timestart>1259827200</timestart>
<timeend>1259827200</timeend>
<description>This is the event.</description>
<url>http://example.com/calendar/view.php?view=day&amp;course=12088&a… </event>
</events>
</course>
</courses>
<status>success</status>
</get_user_course_events></Service_User>
GET_USER_GRADES
The Conduit user and course Web services provide external systems with a way to extract grades from Moodle. There are settings specifically for these services and they can be found in the Grades section under the Conduit Settings > Web services sub-tab. Conduit provides two endpoints to retrieve Moodle grades.
POST PARAMETERS:
string token: (Required) Set to the Token setting value used in Conduit Settings > Web services sub-tab.
string method: (Required) Must be set to get_user_grades.
string user: (Required) The user to return the grades for.
int batchsize: (Optional) The number of grades to return. Must be less than 10,000.
int lastprocessedid: (Optional) The last grade ID processed and returned from the Web service. This helps with crawling through all of the Moodle grades because if you pass it, the service will only return grades with IDs that are greater than this one.
int starttime: (Optional) Use to get grades that have been modified after this time. Pass in the form of a UNIX time stamp.
int endtime: (Optional) Use to get grades that have been modified before this time. Pass in the form of a UNIX time stamp.
string course: (Optional) Use to get the grades from a specific course for the user. The value must be either course shortname or idnumber based on the “Course ID” setting found in Conduit Settings > General sub-tab. If omitted, all user grades are returned.
string itemtypes: (Optional, Default: DEFAULT_SET) Pass a CSV list of grade item types to include. For all item types, pass an empty string. To get the default grade items that are configured through Conduit, do not pass this parameter or set it to DEFAULT_SET.
RETURNED XML SCHEMA
Both grade Web services endpoints return the same XML schema. The schema returns the grade items and their grades. The user and course tags act like dictionaries, as they contain all of the users and courses that the grade items and grades belong to. Use the courseid and the userid tags to look up their corresponding courses and users. The lastprocessedid tag is the last grade ID that the Web service processed. Use this value if you wish to use the lastprocessedid Web service parameter.
<?xml version=”1.0″ encoding=”UTF-8″?><Service_User generator=”zend” version=”1.0″>
<get_user_grades>
<users>
<id_X>
<user>
<id>integer</id>
<fullname>string</fullname>
<username>string</username>
<idnumber>string</idnumber>
</user>
</id_X>
</users>
<courses>
<id_X>
<course>
<id>integer</id>
<fullname>string</fullname>
<shortname>string</shortname>
<idnumber>string</idnumber>
</course>
</id_X>
</courses>
<gradeitems>
<gradeitem>
<courseid>integer</courseid>
<itemtype>string(course, mod, category, manual, null)</itemtype>
<itemname>string</itemname>
<itemmodule>string</itemmodule>
<iteminstance>integer</iteminstance>
<grades>
<grade>
<id>integer</id>
<userid>integer</userid>
<finalgrade>number</finalgrade>
<gradeletter>string</gradeletter>
<gradepercent>string</gradepercent>
<timemodified>integer</timemodified>
<deleted>1/0</deleted>
</grade>
</grades>
</gradeitem>
</gradeitems>
<lastprocessedid>integer</lastprocessedid>
<status>success/fail</status>
</get_user_grades></Service_User>
item types: course, mod, category, manual, null
User Handle
POST PARAMETERS
- string token: (Required) Set to the Token setting value used in Conduit Settings > Web services sub-tab.
- string method: (Required) Must be set to handle.
- string xml: (Required) XML schema that contains data for performing operations on Conduit records.
VALID ACTIONS
- Create
- Update
- Delete
CREATE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”create”>
<mapping name=”username”>string</mapping>
<mapping name=”auth”>string</mapping>
<mapping name=”mnethostid”>integer</mapping>
<mapping name=”password”>string</mapping>
<mapping name=”idnumber”>string</mapping>
<mapping name=”firstname”>string</mapping>
<mapping name=”lastname”>string</mapping>
<mapping name=”email”>string</mapping>
<mapping name=”phone1″>string</mapping>
<mapping name=”phone2″>string</mapping>
<mapping name=”institution”>string</mapping>
<mapping name=”department”>string</mapping>
<mapping name=”address”>string</mapping>
<mapping name=”city”>string</mapping>
<mapping name=”country”>string</mapping>
<mapping name=”lang”>string</mapping>
<mapping name=”theme”>string</mapping>
<mapping name=”timezone”>string</mapping>
<mapping name=”picture”>integer</mapping>
<mapping name=”url”>string</mapping>
<mapping name=”description”>string</mapping>
<mapping name=”mailformat”>integer</mapping>
<mapping name=”maildigest”>integer</mapping>
<mapping name=”maildisplay”>integer</mapping>
<mapping name=”htmleditor”>integer</mapping>
<mapping name=”autosubscribe”>integer</mapping>
<mapping name=”trackforums”>string</mapping>
<mapping name=”imagealt”>integer</mapping>
<mapping name=”textarea”>string</mapping>
</datum></data>
UPDATE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”update”>
<mapping name=”username”>string</mapping>
<mapping name=”auth”>string</mapping>
<mapping name=”mnethostid”>integer</mapping>
<mapping name=”password”>string</mapping>
<mapping name=”idnumber”>string</mapping>
<mapping name=”firstname”>string</mapping>
<mapping name=”lastname”>string</mapping>
<mapping name=”email”>string</mapping>
<mapping name=”phone1″>string</mapping>
<mapping name=”phone2″>string</mapping>
<mapping name=”institution”>string</mapping>
<mapping name=”department”>string</mapping>
<mapping name=”address”>string</mapping>
<mapping name=”city”>string</mapping>
<mapping name=”country”>string</mapping>
<mapping name=”lang”>string</mapping>
<mapping name=”theme”>string</mapping>
<mapping name=”timezone”>string</mapping>
<mapping name=”picture”>integer</mapping>
<mapping name=”url”>string</mapping>
<mapping name=”description”>string</mapping>
<mapping name=”mailformat”>integer</mapping>
<mapping name=”maildigest”>integer</mapping>
<mapping name=”maildisplay”>integer</mapping>
<mapping name=”htmleditor”>integer</mapping>
<mapping name=”autosubscribe”>integer</mapping>
<mapping name=”trackforums”>string</mapping>
<mapping name=”imagealt”>integer</mapping>
<mapping name=”textarea”>string</mapping>
</datum></data>
DELETE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”delete”>
<mapping name=”username”>string</mapping>
</datum></data>
RESPONSE XML DEFINITION
<Service_User generator=”zend” version=”1.0″>
<handle>
<message>MESSAGE</message>
<status>STATUS</status>
</handle></Service_Rest_User>
GET_COURSE
Get Moodle course settings.
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to get_course.
string value: (Required) The course value to lookup, such as the course’s shortname.
string field: (Optional, default = shortname) The Moodle table field to lookup against. Can be id, shortname or idnumber.
RETURNED XML SCHEMA
<?xml version=”1.0″ encoding=”UTF-8″?><Service_Course generator=”zend” version=”1.0″> <get_course> <course> <id>int</id> <category>int</category> <sortorder>int</sortorder> <password>string</password> <fullname>string</fullname> <shortname>string</shortname> <idnumber>string</idnumber> <summary>string</summary> <format>string</format> <showgrades>int</showgrades> <newsitems>int</newsitems> <startdate>int</startdate> <enrolperiod>int</enrolperiod> <numsections>int</numsections> <marker>int</marker> <maxbytes>int</maxbytes> <showreports>int</showreports> <visible>int</visible> <hiddensections>int</hiddensections> <groupmode>int</groupmode> <groupmodeforce>int</groupmodeforce> <defaultgroupingid>int</defaultgroupingid> <lang>string</lang> <theme>string</theme> <timecreated>int</timecreated> <timemodified>int</timemodified> <requested>int</requested> <restrictmodules>int</restrictmodules> </course> <status>success</status> </get_course></Service_Course>
GET_COURSE_GRADES
The Conduit course Web services method get_course_grades provided external systems with a way to extract grades from Conduit. There are settings specifically for the grades web services and are found in the Grades section under the Conduit Settings tab > Web services sub-tab. get_course_grades returns all grades for all users in the course even if they have been unenrolled from the course.
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Set to get_course_grades.
string course: (Optional) Use to get the grades from a specific course for the user. The value must be either course shortname or idnumber based on the Course ID setting found in Conduit Settings tab > General sub-tab. If omitted, all courses are returned.
int batchsize: (Optional) The number of grades to return. Must be less than 10,000.
int lastprocessedid: (Optional) The last grade ID processed and returned from the Web service. This helps with crawling through all of the Moodle grades because if you pass it, the service will only return grades with IDs that are greater than this one.
int starttime: (Optional) Use to get grades that have been modified after this time. Pass in the form of a UNIX time stamp.
int endtime: (Optional) Use to get grades that have been modified before this time. Pass in the form of a UNIX time stamp.
string itemtypes: (Optional, Default: DEFAULT_SET) Pass a CSV list of grade item types to include. For all item types, pass an empty string. To get the default grade items that are configured through Conduit, then do not pass this parameter or set it to DEFAULT_SET.
RETURNED XML SCHEMA
The schema returns the grade items and their grades. The user and course tags act like dictionaries, as they contain all of the users and courses that the grade items and grades belong to. Use the courseid and the userid tags to look up their corresponding courses and users. The lastprocessedid tag is the last grade ID that the Web service processed. Use this value if you wish to use the lastprocessedid Web service parameter.
<?xml version=”1.0″ encoding=”UTF-8″?><Service_User generator=”zend” version=”1.0″>
<get_course_grades>
<users>
<id_X>
<user>
<id>integer</id>
<fullname>string</fullname>
<username>string</username>
<idnumber>string</idnumber>
</user>
</id_X>
</users>
<courses>
<id_X>
<course>
<id>integer</id>
<fullname>string</fullname>
<shortname>string</shortname>
<idnumber>string</idnumber>
</course>
</id_X>
</courses>
<gradeitems>
<gradeitem>
<courseid>integer</courseid>
<itemtype>string(course, mod, category, manual, null)</itemtype>
<itemname>string</itemname>
<itemmodule>string</itemmodule>
<iteminstance>integer</iteminstance>
<grades>
<grade>
<id>integer</id>
<userid>integer</userid>
<finalgrade>number</finalgrade>
<gradeletter>string</gradeletter>
<gradepercent>string</gradepercent>
<timemodified>integer</timemodified>
<deleted>1/0</deleted>
</grade>
</grades>
</gradeitem>
</gradeitems>
<lastprocessedid>integer</lastprocessedid>
<status>success/fail</status>
</get_course_grades></Service_User>
Item types: course, mod, category, manual, null.
Course Handle
POST PARAMETERS
- string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
- string method: (Required) Must be set to handle.
- string xml: (Required) XML schema that contains data for performing operations on Conduit records.
VALID ACTIONS
- Create
- Update
- Delete
CREATE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”create”>
<mapping name=”shortname”>string</mapping>
<mapping name=”category”>string</mapping>
<mapping name=”password”>string</mapping>
<mapping name=”fullname”><string/mapping>
<mapping name=”idnumber”>string</mapping>
<mapping name=”summary”>string</mapping>
<mapping name=”summaryformat”>integer</mapping>
<mapping name=”format”>string</mapping>
<mapping name=”showgrades”>integer</mapping>
<mapping name=”newsitems”>integer</mapping>
<mapping name=”startdate”>integer</mapping>
<mapping name=”numsections”>integer</mapping>
<mapping name=”marker”>integer</mapping>
<mapping name=”maxbytes”>integer</mapping>
<mapping name=”showreports”>integer</mapping>
<mapping name=”visible”>integer</mapping>
<mapping name=”hiddensections”>integer</mapping>
<mapping name=”groupmode”>integer</mapping>
<mapping name=”groupmodeforce”>integer</mapping>
<mapping name=”defaultgroupingid”></mapping>
<mapping name=”lang”>string</mapping>
<mapping name=”theme”>string</mapping>
<mapping name=”requested”>integer</mapping>
<mapping name=”restrictmodules”>integer</mapping>
<mapping name=”enablecompletion”>integer</mapping>
<mapping name=”completionstartonenrol”>integer</mapping>
<mapping name=”completionnotify”>integer</mapping>
<mapping name=”coursetemplate”>string</mapping>
</datum></data>
UPDATE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”update”>
<mapping name=”shortname”>string</mapping>
<mapping name=”category”>string</mapping>
<mapping name=”password”>string</mapping>
<mapping name=”fullname”><string/mapping>
<mapping name=”idnumber”>string</mapping>
<mapping name=”summary”>string</mapping>
<mapping name=”summaryformat”>integer</mapping>
<mapping name=”format”>string</mapping>
<mapping name=”showgrades”>integer</mapping>
<mapping name=”newsitems”>integer</mapping>
<mapping name=”startdate”>integer</mapping>
<mapping name=”numsections”>integer</mapping>
<mapping name=”marker”>integer</mapping>
<mapping name=”maxbytes”>integer</mapping>
<mapping name=”showreports”>integer</mapping>
<mapping name=”visible”>integer</mapping>
<mapping name=”hiddensections”>integer</mapping>
<mapping name=”groupmode”>integer</mapping>
<mapping name=”groupmodeforce”>integer</mapping>
<mapping name=”defaultgroupingid”></mapping>
<mapping name=”lang”>string</mapping>
<mapping name=”theme”>string</mapping>
<mapping name=”requested”>integer</mapping>
<mapping name=”restrictmodules”>integer</mapping>
<mapping name=”enablecompletion”>integer</mapping>
<mapping name=”completionstartonenrol”>integer</mapping>
<mapping name=”completionnotify”>integer</mapping>
<mapping name=”coursetemplate”>string</mapping>
</datum></data>
DELETE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”delete”>
<mapping name=”shortname”>string</mapping>
</datum></data>
RESPONSE XML DEFINITION
<Service_Course generator=”zend” version=”1.0″>
<handle>
<message>MESSAGE</message>
<status>STATUS</status>
</handle></Service_Rest_Course>
Enrollment Handle
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to handle.
string xml: (Required) XML schema that contains data for performing operations on Conduit records.
VALID ACTIONS
Create
Update
Delete
CREATE ACTION XML DEFINITION
<?xml version=’1.0′?><data>
<datum action=”create”>
<mapping name=”coursekey”>string</mapping>
<mapping name=”userkey”>string</mapping>
<mapping name=”rolekey”>string</mapping>
<mapping name=”timestart”>integer</mapping>
<mapping name=”timeend”>integer</mapping>
</datum></data>
UPDATE ACTION XML DEFINITION
<?xml version=’1.0′?><data>
<datum action=”update”>
<mapping name=”coursekey”>string</mapping>
<mapping name=”userkey”>string</mapping>
<mapping name=”rolekey”>string</mapping>
<mapping name=”timestart”>integer</mapping>
<mapping name=”timeend”>integer</mapping>
</datum></data>
DELETE ACTION XML DEFINITION
<?xml version=’1.0′?><data>
<datum action=”delete”>
<mapping name=”coursekey”>string</mapping>
<mapping name=”userkey”>string</mapping>
</datum></data>
RESPONSE XML DEFINITION
<Service_Enrol generator=”zend” version=”1.0″>
<handle>
<message>MESSAGE</message>
<status>STATUS</status>
</handle></Service_Rest_Enrol>
Role assignment Handle
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to handle.
string xml: (Required) XML schema that contains data for performing operations on Conduit records.
VALID ACTIONS
Create
Update
Delete
CREATE ACTION XML DEFINITION
<?xml version=’1.0′?><data>
<datum action=”create”>
<mapping name=”context”>course|user</mapping>
<mapping name=”moodlekey”>string</mapping>
<mapping name=”userkey”>string</mapping>
<mapping name=”rolekey”>string</mapping>
<mapping name=”timestart”>integer</mapping>
<mapping name=”timeend”>integer</mapping>
</datum></data>
UPDATE ACTION XML DEFINITION
<?xml version=’1.0′?><data>
<datum action=”update”>
<mapping name=”context”>course|user</mapping>
<mapping name=”moodlekey”>string</mapping>
<mapping name=”userkey”>string</mapping>
<mapping name=”rolekey”>string</mapping>
<mapping name=”timestart”>integer</mapping>
<mapping name=”timeend”>integer</mapping>
</datum></data>
DELETE ACTION XML DEFINITION
<?xml version=’1.0′?><data>
<datum action=”delete”>
<mapping name=”context”>course|user</mapping>
<mapping name=”moodlekey”>string</mapping>
<mapping name=”userkey”>string</mapping>
<mapping name=”rolekey”>string</mapping>
</datum></data>
RESPONSE XML DEFINITION
<Service_Enrol generator=”zend” version=”1.0″>
<handle>
<message>MESSAGE</message>
<status>STATUS</status>
</handle></Service_Rest_Enrol>
GET_GROUPS
Return the settings information for the groups in a course.
POST PARAMETERS
string method: (Required) Must be set to get_groups.
string value: (Required) The course value to look up.
string field: (Optional, Default: idnumber) The course field to match the value against, can be id, shortname or idnumber.
RESPONSE XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><Service_Groups generator=”zend” version=”1.0″>
<get_groups>
<groups>
<group>
<courseid>int</courseid>
<name>string</name>
<description>string</description>
<enrolmentkey>string</enrolmentkey>
<picture>int</picture>
<hidepicture>int</hidepicture>
<timecreated>int</timecreated>
<timemodified>int</timemodified>
<id>int</id>
</group>
</groups>
<status>success</status>
</get_groups></Service_Groups>
Groups Handle
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to handle.
string xml: (Required) XML schema that contains data for performing operations on Conduit records.
VALID ACTIONS
Create
Update
Delete
CREATE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”create”>
<mapping name=”coursekey”>string</mapping>
<mapping name=”groupkey”>string</mapping>
<mapping name=”description”>string</mapping>
<mapping name=”enrollmentkey”>string</mapping>
<mapping name=”hidepicture”>integer</mapping>
</datum></data>
UPDATE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”update”>
<mapping name=”coursekey”>string</mapping>
<mapping name=”groupkey”>string</mapping>
<mapping name=”newgroupkey”>string</mapping>
<mapping name=”description”>string</mapping>
<mapping name=”enrollmentkey”>string</mapping>
<mapping name=”hidepicture”>integer</mapping>
</datum></data>
DELETE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”delete”>
<mapping name=”coursekey”>string</mapping>
<mapping name=”groupkey”>string</mapping>
</datum></data>
RESPONSE XML DEFINITION
<Service_Groups generator=”zend” version=”1.0″>
<handle>
<message>MESSAGE</message>
<status>STATUS</status>
</handle></Service_Rest_Groups>
Group Members Handle
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to handle.
string xml: (Required) XML schema that contains data for performing operations on Conduit records.
VALID ACTIONS
Create
Delete
CREATE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”create”>
<mapping name=”coursekey”>string</mapping>
<mapping name=”userkey”>string</mapping>
<mapping name=”groupkey”>string</mapping>
</datum></data>
DELETE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”delete”>
<mapping name=”coursekey”>string</mapping>
<mapping name=”userkey”>string</mapping>
<mapping name=”groupkey”>string</mapping>
</datum></data>
RESPONSE XML DEFINITION
<Service_group_members generator=”zend” version=”1.0″>
<handle>
<message>MESSAGE</message>
<status>STATUS</status>
</handle></Service_Rest_Group_Members>
Cohort Members Handle
POST PARAMETERS
string token: (Required) Set to the Token setting value used in Conduit Settings tab > Web services sub-tab.
string method: (Required) Must be set to handle.
string xml: (Required) XML schema that contains data for performing operations on Conduit records.
VALID ACTIONS
Create
Delete
CREATE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”create”>
<mapping name=”externalkey”>string</mapping>
<mapping name=”userkey”>string</mapping>
<mapping name=”cohortkey”>string</mapping>
</datum></data>
DELETE ACTION XML DEFINITION
<?xml version=”1.0″ encoding=”UTF-8″?><data>
<datum action=”delete”>
<mapping name=”externalkey”>string</mapping>
<mapping name=”userkey”>string</mapping>
<mapping name=”cohortkey”>string</mapping>
</datum></data>
RESPONSE XML DEFINITION
<Service_cohort_members generator=”zend” version=”1.0″>
<handle>
<message>MESSAGE</message>
<status>STATUS</status>
</handle></Service_Rest_Cohort_Members>
Sample Calls
These examples are designed to give you a place to work from when creating your own calls. Keep in mind that the specific data structures, urls, and token values are not going to work for your site.
Example Handles
Create User Example
This POST creates a new user (or updates an existing user). When testing, index the username, idnumber, names, and email to new values each iteration. Feel free to use your own email address source. Gmail is handy because you can index emails with a ‘+XXX’ and Gmail ignores the text between the + and the @.
https://mysiteurl.openlms/blocks/conduit/webservices/rest/user.php?token=CoolPassword1&method=handle&xml=<?xml version='1.0'?> <data> <datum action="create"> <mapping name="username">user1112</mapping> <mapping name="idnumber">user1112</mapping> <mapping name="firstname">user1112</mapping> <mapping name="lastname">WSTest</mapping> <mapping name="email">mygmail+user1112@gmail.com</mapping> </datum> </data>
Create Course Example
This POST creates a new course off a template course, PLD101. The course shortname, idnumber, and fullname should index up on each new iteration. You will also need a template target that uses the shortname that matches the one supplied. The course is created from a template and will take 60 seconds or more to process. It is recommended that you set the General Settings in Conduit to restore from a backup to speed up the process. (This avoids making a backup each time a course is made from that template.)
https://mysiteurl.openlms/blocks/conduit/webservices/rest/course.php?token=CoolPassword1&method=handle&xml=<?xml version='1.0'?> <data> <datum action="create"> <mapping name="shortname">conduitws0002</mapping> <mapping name="idnumber">cws002</mapping> <mapping name="category">Conduit Web Service</mapping> <mapping name="fullname">Sample Course 002</mapping> <mapping name="coursetemplate">PLD101</mapping> </datum> </data>
Create Enrollment Example
This POST creates an enrollment action for the specified user in the specified course with the specified role. My site uses the users idnumber as the key record field and the shortname for the course and the shortname for the role. The key record value for each record type is controlled in the Conduit General settings.
https://mysiteurl.openlms/blocks/conduit/webservices/rest/enroll.php?token=CoolPassword1&method=handle&xml=<?xml version="1.0" encoding="UTF-8"?> <data> <datum action="create"> <mapping name="course">conduitws0002</mapping> <mapping name="user">user1112</mapping> <mapping name="role">student</mapping> </datum> </data>
Example GET methods
GET Course Grades
This call returns all course grades (not item grades) for all users in the specified course. The returns are scores, percent, and letter for each user enrolled in the course in a role that gets graded.
https://mysiteurl.openlms/blocks/conduit/webservices/rest/course.php?method=get_course_grades&token=CoolPassword1&course=Alg204
GET User Grades
Returns all grades for a specific user, across their courses. It pulls just course grades in all formats (score, percent, and letter) for each course that the user has grades in. You can modify to pull all grades (item grades) which turns into a lot of data typically. The behavior is managed in the Web service settings in Conduit.
https://mysiteurl.openlms/blocks/conduit/webservices/rest/user.php?method=get_user_grades&token=CoolPassword1&user=4
GET User Course Recent Activity
This user endpoint web service method provides an external interface to retrieve information about all activities that have been added, updated or deleted for a period of time within the courses a user is enrolled in. Users must be identified by username or userid. Optional fields can be used to specify a single course and frame the time window to be shorter than the default for “recent”.
https://mysiteurl.openlms/blocks/conduit/webservices/rest/user.php?method=get_user_course_recent_activity&token=CoolPassword1&userid=4
Sample Responses
Responses from Conduit will be dependent on the nature of the call to some extent. All calls will generate a status code response (200 for success, 400 invalid on error, etc.) and an XML package with some details. Handles are typically met only with a success message or error with details, while GET methods should expect an XML package with the details requested.
Success, Handle
200
<?xml version="1.0" encoding="UTF-8"?>
<blocks_conduit_model_service_user generator="zend" version="1.0"><handle><response>Request handled</response><status>success</status></handle></blocks_conduit_model_service_user>
Error, Handle
400
Error return
<?xml version="1.0" encoding="UTF-8"?>
<blocks_conduit_model_service_user generator="zend" version="1.0"><handle><message>Data failed to validate, errors: Missing values for the following required fields: username. Debug info: Array
(
[action] => create
[data] => Array
(
[idnumber] => user1114
[email] => user1114@gmail.com
)
[notmapped] => Array
(
[username] => user1114
[firstname] => user1114
[lastname] => WSTest
)
)
There were errors when processing this transaction. If there is a file associated to it, it will be moved to the quarantine folder "/srv/clientdata/na02/sandbox2sb/conduit/quarantine/transaction_197".</message><status>0</status></handle></blocks_conduit_model_service_user>
Success, GET get_user_grades
200
<?xml version="1.0" encoding="UTF-8"?>
<blocks_conduit_model_service_user generator="zend" version="1.0"><get_user_grades><users><id_34><user><id>34</id><fullname>Brian Johnson</fullname><username>user4</username><idnumber>4</idnumber></user></id_34></users><courses><id_33><course><id>33</id><fullname>Algebra 101</fullname><shortname>MATH203</shortname><idnumber></idnumber></course></id_33><id_103><course><id>103</id><fullname>Algebra 202</fullname><shortname>Alg202</shortname><idnumber></idnumber></course></id_103><id_115><course><id>115</id><fullname>Public Demo - Snap Theme</fullname><shortname>publicdemo3</shortname><idnumber>pd003</idnumber></course></id_115><id_163><course><id>163</id><fullname>Public Demo - Boost Theme</fullname><shortname>publicdemo4</shortname><idnumber></idnumber></course></id_163><id_201><course><id>201</id><fullname>Economics for Business Decision Making</fullname><shortname>proed1</shortname><idnumber></idnumber></course></id_201><id_244><course><id>244</id><fullname>Algebra 204</fullname><shortname>Alg204</shortname><idnumber></idnumber></course></id_244><id_548><course><id>548</id><fullname>Managing High-Performing Teams</fullname><shortname>template_mhpt</shortname><idnumber></idnumber></course></id_548></courses><gradeitems><gradeitem><courseid>33</courseid><itemtype>course</itemtype><itemname></itemname><itemmodule></itemmodule><iteminstance>42</iteminstance><grades><grade><id>168</id><userid>34</userid><finalgrade>81.53846</finalgrade><gradeletter>B-</gradeletter><gradepercent>81.54 %</gradepercent><timemodified></timemodified><deleted>0</deleted></grade></grades></gradeitem><gradeitem><courseid>115</courseid><itemtype>course</itemtype><itemname></itemname><itemmodule></itemmodule><iteminstance>156</iteminstance><grades><grade><id>627</id><userid>34</userid><finalgrade></finalgrade><gradeletter>-</gradeletter><gradepercent>-</gradepercent><timemodified>1462918673</timemodified><deleted>0</deleted></grade></grades></gradeitem><gradeitem><courseid>163</courseid><itemtype>course</itemtype><itemname></itemname><itemmodule></itemmodule><iteminstance>277</iteminstance><grades><grade><id>1834</id><userid>34</userid><finalgrade>100.00000</finalgrade><gradeletter>A</gradeletter><gradepercent>100.00 %</gradepercent><timemodified></timemodified><deleted>0</deleted></grade></grades></gradeitem><gradeitem><courseid>201</courseid><itemtype>course</itemtype><itemname></itemname><itemmodule></itemmodule><iteminstance>329</iteminstance><grades><grade><id>1997</id><userid>34</userid><finalgrade>56.00000</finalgrade><gradeletter>A</gradeletter><gradepercent>100.00 %</gradepercent><timemodified>1441300658</timemodified><deleted>0</deleted></grade></grades></gradeitem><gradeitem><courseid>244</courseid><itemtype>course</itemtype><itemname></itemname><itemmodule></itemmodule><iteminstance>418</iteminstance><grades><grade><id>2353</id><userid>34</userid><finalgrade>325.98212</finalgrade><gradeletter>F</gradeletter><gradepercent>48.1 %</gradepercent><timemodified>1665689659</timemodified><deleted>0</deleted></grade></grades></gradeitem><gradeitem><courseid>103</courseid><itemtype>course</itemtype><itemname></itemname><itemmodule></itemmodule><iteminstance>462</iteminstance><grades><grade><id>4503</id><userid>34</userid><finalgrade>100.00000</finalgrade><gradeletter>A</gradeletter><gradepercent>100.00 %</gradepercent><timemodified>1512637624</timemodified><deleted>0</deleted></grade></grades></gradeitem><gradeitem><courseid>548</courseid><itemtype>course</itemtype><itemname></itemname><itemmodule></itemmodule><iteminstance>1049</iteminstance><grades><grade><id>5245</id><userid>34</userid><finalgrade>95.50000</finalgrade><gradeletter>A</gradeletter><gradepercent>95.50 %</gradepercent><timemodified>1634244897</timemodified><deleted>0</deleted></grade></grades></gradeitem></gradeitems><lastprocessedid>5245</lastprocessedid><status>success</status></get_user_grades></blocks_conduit_model_service_user>
Error, GET get_course_grades
400
<?xml version="1.0" encoding="UTF-8"?>
<blocks_conduit_model_service_course generator="zend" version="1.0"><get_course_grades><response><message>No courses found with = Alg2054</message></response><status>failed</status></get_course_grades></blocks_conduit_model_service_course>