API
Neill Magill
ROGO 6.1.0
Web services
The following restful endpoints are available:
Handler
All module management requests should hit /api/modulemanagement.
Schema
The module management schema is available at /api/schema/modulemanagement/managementrequest.xsd
Create
In order to create a module the create tag needs to be sent containing the name, modulecode, school and faculty tags.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/modulemanagement/managementrequest.xsd">
<create id="str1234">
<modulecode>abc</modulecode>
<name>abc</name>
<school>abc</school>
<faculty>abc</faculty>
</create>
</moduleManagementRequest>
If the operation is successful the response returns the id of the created module in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementResponse>
<create id="str1234">
<id>23</id>
<status_code>100</status_code>
<status>OK</status>
</create>
</moduleManagementResponse>
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?> <moduleManagementResponse> <create id="str1234"> <id>12</id> <status_code>505</status_code> <status>Module already exists</status> </create> </moduleManagementResponse>
Update
In order to update a module the update tag needs to be sent containing an id tag (or external id) of the module to be updated.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/modulemanagement/managementrequest.xsd">
<update id="1">
<id>23</id>
<name>abcd</name>
</update>
</moduleManagementRequest>
If the operation is successful the response returns the id of the updated module in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementResponse>
<update id="1">
<id>23</id>
<status_code>100</status_code>
<status>OK</status>
</update>
</moduleManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementResponse>
<update id="1">
<id></id>
<status_code>501</status_code>
<status>Module does not exist</status>
</update>
</moduleManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | update | The id used to identify the module to update | Only used when updating |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
| externalsys | create/update | The name of the external system | If using the externalid as your primary identifier instead of id |
| modulecode | create/update | The code of the module | When creating |
| name | create/update | The name of the module | When creating |
| school | create/update | School the module is in i.e. 'School of Computer Science' | When creating and if updating faculty |
| faculty | create/update | Faculty the module is in i.e. 'Faculty of Science'. | Only when school attribute supplied |
| sms | create/update | Student management system used to create module | No |
Delete
In order to delete a module the delete tag needs to be sent containing an id tag of the module to be deleted.
<?xml version="1.0" encoding="utf-8"?> <moduleManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/modulemanagement/managementrequest.xsd"> <delete id="az"> <id>23</id> </delete> </moduleManagementRequest>
If the operation is successful the response returns the id of the deleted module in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementResponse>
<delete id="az">
<id>23</id>
<status_code>100</status_code>
<status>OK</status>
</delete>
</moduleManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementResponse>
<delete id="az">
<id></id>
<status>You do not have permission to run this action</status>
</delete>
</moduleManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | delete | The id used to identify the module to delete | Yes |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
Response Codes
Possible response codes are as follows:
| Code | Description |
|---|---|
100 | Action successfully performed |
500 | Error deleting module |
| 501 | Module does not exist |
| 502 | Cannot delete module as in use |
| 503 | Error updating module |
| 504 | Error creating module |
| 505 | Module already exists |
| 506 | Faculty not supplied |
| 511 | School not supplied |
| 512 | Nothing to update |
| 513 | School External ID already in use |
Handler
All school management requests should hit /api/schoolmanagement.
Schema
The school management schema is available at /api/schema/schoolmanagement/managementrequest.xsd
Create
In order to create a school the create tag needs to be sent containing the name, and faculty tags.
<?xml version="1.0" encoding="utf-8"?>
<schoolManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/schoolmanagement/managementrequest.xsd">
<create id="str1234">
<name>abcd</name>
<faculty>abc</faculty>
</create>
</schoolManagementRequest>
If the operation is successful the response returns the id of the created school in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<schoolManagementResponse>
<create id="str1234">
<id>12</id>
<status_code>100</status_code>
<status>OK</status>
</create>
</schoolManagementResponse>
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<schoolManagementResponse>
<create id="str1234">
<id>12</id>
<status_code>606</status_code>
<status>School already exists</status>
</create>
</schoolManagementResponse>
Update
In order to update a module the update tag needs to be sent containing an id tag (or external id) of the school to be updated.
<?xml version="1.0" encoding="utf-8"?>
<schoolManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/schoolmanagement/managementrequest.xsd">
<update id="13">
<id>12</id>
<name>abcde</name>
</update>
</schoolManagementRequest>
If the operation is successful the response returns the id of the updated school in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<schoolManagementResponse>
<update id="13">
<id>12</id>
<status_code>100</status_code>
<status>OK</status>
</update>
</schoolManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<schoolManagementResponse>
<update id="1">
<id></id>
<status_code>605</status_code>
<status>Faculty does not exist</status>
</update>
</schoolManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | update | The id used to identify the school to update | Only used when updating |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
| externalsys | create/update | The name of the external system | If using the externalid as your primary identifier instead of id |
| school | create/update | The School i.e. 'School of Computer Science' | When creating |
| faculty | create/update | Faculty the school is in i.e. 'Faculty of Science'. | Only when creating a new school |
Delete
In order to delete a module the delete tag needs to be sent containing an id tag of the school to be deleted.
<?xml version="1.0" encoding="utf-8"?>
<schoolManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/schoolmanagement/managementrequest.xsd">
<delete id="qwerty">
<id>12</id>
</delete>
</schoolManagementRequest>
If the operation is successful the response returns the id of the deleted school in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<schoolManagementResponse>
<delete id="qwerty">
<id>12</id>
<status_code>100</status_code>
<status>OK</status>
</delete>
</schoolManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<schoolManagementResponse>
<delete id="qwerty">
<id></id>
<status>You do not have permission to run this action</status>
</delete>
</schoolManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | delete | The id used to identify the school to delete | Yes |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
Response Codes
Possible response codes are as follows:
| Code | Description |
|---|---|
100 | Action successfully performed |
600 | Error deleting school |
| 601 | School does not exist |
| 602 | Error updating school |
| 603 | Error creating school |
| 604 | Cannot delete school in use |
| 605 | Faculty supplied invalid |
| 606 | School already exists |
| 607 | Nothing to update |
| 608 | Faculty External ID invalid |
Handler
All course management requests should hit /api/coursemanagement.
Schema
The course management schema is available at /api/schema/coursemanagement/managementrequest.xsd
Create
In order to create a course the create tag needs to be sent containing the name, description and school tags (ty as well if new school).
<?xml version="1.0" encoding="utf-8"?>
<courseManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/coursemanagement/managementrequest.xsd">
<create id="str1234">
<name>rogotest</name>
<description>rogo test</description>
<school>test</school>
</create>
</courseManagementRequest>
If the operation is successful the response returns the id of the created course in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<courseManagementResponse>
<create id="str1234">
<id>13</id>
<status_code>100</status_code>
<status>OK</status>
</create>
</courseManagementResponse>
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?> <courseManagementResponse> <create id="str1234"> <id>13</id> <status_code>306</status_code> <status>Course already exists</status> </create> </courseManagementResponse>
Update
In order to update a module the update tag needs to be sent containing an id tag of the course to be updated.
<?xml version="1.0" encoding="utf-8"?>
<courseManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/coursemanagement/managementrequest.xsd">
<update id="str1234">
<id>13</id>
<school>test 2</school>
<faculty>test faculty</faculty>
</update>
</courseManagementRequest>
If the operation is successful the response returns the id of the updated course in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<courseManagementRequest>
<update id="str1234">
<id>13</id>
<status_code>100</status_code>
<status>OK</status>
</update>
</courseManagementRequest>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<courseManagementRequest>
<update id="1">
<id></id>
<status_code>301</status_code>
status>Course does not exist</status>
</update>
</courseManagementRequest>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | update | The id used to identify the course to update | Only used when updating |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
| externalsys | create/update | The name of the external system | If using the externalid as your primary identifier instead of id |
| name | create/update | The code of the course i.e. EA03 | When creating |
| description | create/update | Description of the course i.e. 'Computer Science with Artificial Intelligence (2+2)(4 Year UG (yr 1 foundation))' | When creating |
| school | create/update | School the course is in i.e. 'School of Computer Science' | When creating |
| faculty | create/update | Faculty the school is in i.e. 'Faculty of Science'. | Only when school attribute supplied |
Delete
In order to delete a module the delete tag needs to be sent containing an id tag of the course to be deleted.
<?xml version="1.0" encoding="utf-8"?>
<courseManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/coursemanagement/managementrequest.xsd">
<delete id="qwerty">
<id>13</id>
</delete>
</courseManagementRequest>
If the operation is successful the response returns the id of the deleted course in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<courseManagementRequest>
<delete id="qwerty">
<id>13</id>
<status_code>100</status_code>
<status>OK</status>
</delete>
</courseManagementRequest>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<courseManagementRequest>
<delete id="qwerty">
<id></id>
<status>You do not have permission to run this action</status>
</delete>
</courseManagementRequest>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | delete | The id used to identify the course to delete | Yes |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
Response Codes
Possible response codes are as follows:
| Code | Description |
|---|---|
100 | Action successfully performed |
300 | Error deleting course |
| 301 | Course does not exist |
| 302 | Cannot delete course as in use |
| 303 | Invalid faculty |
| 304 | Error updating course |
| 305 | Error creating course |
| 306 | Course already exists |
| 307 | School not supplied |
| 308 | Request updates nothing |
| 309 | School External ID already in use |
Handler
All faculty management requests should hit /api/facultymanagement.
Schema
The faculty management schema is available at /api/schema/facultymanagement/managementrequest.xsd
Create
In order to create a faculty the create tag needs to be sent containing the name.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/facultymanagement/managementrequest.xsd">
<create id="str1234">
<name>abc</name>
</create>
</facultyManagementRequest>
If the operation is successful the response returns the id of the created faculty in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementResponse>
<create id="str1234">
<id>11</id>
<status_code>100</status_code>
<status>OK</status>
</create>
</facultyManagementResponse>
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementResponse>
<create id="str1234">
<id>10</id>
<status_code>401</status_code>
<status>Faculty already exists</status>
</create>
</facultyManagementResponse>
Update
In order to update a module the update tag needs to be sent containing an id tag of the faculty to be updated.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/facultymanagement/managementrequest.xsd">
<update id="str1234">
<id>11</id>
<name>abcde</name>
</update>
</facultyManagementRequest>
If the operation is successful the response returns the id of the updated faculty in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementResponse>
<update id="str1234">
<id>11</id>
<status_code>100</status_code>
<status>OK</status>
</update>
</facultyManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementResponse>
<update id="str1234">
<id></id>
<status_code>402</status_code>
<status>Faculty not updated</status>
</update>
</facultyManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | update | The id used to identify the faculty to update | Only used when updating |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
| externalsys | create/update | The name of the external system | If using the externalid as your primary identifier instead of id |
| name | create/update | A Faculty i.e. 'Faculty of Science'. | Yes |
Delete
In order to delete a faculty the delete tag needs to be sent containing an id tag of the module to be deleted.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/facultymanagement/managementrequest.xsd">
<delete id="str1234">
<id>10</id>
</delete>
</facultyManagementRequest>
If the operation is successful the response returns the id of the deleted faculty in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementResponse>
<delete id="str1234">
<id>11</id>
<status_code>100</status_code>
<status>OK</status>
</delete>
</facultyManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementResponse>
<delete id="str1234">
<id></id>
<status_code>404</status_code>
<status>Faculty not deleted, as contains schools</status>
</delete>
</facultyManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | delete | The id used to identify the faculty to delete | yes |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
Response Codes
Possible response codes are as follows:
| Code | Description |
|---|---|
100 | Action successfully performed |
400 | Error deleting faculty |
| 401 | Faculty does not exist |
| 402 | Error updating faculty |
| 403 | Error creating faculty |
| 404 | Cannot delete faculty as in use |
| 405 | Faculty already exists |
| 406 | Invalid academic session supplied |
| 407 | Nothing to update |
Handler
All user management requests should hit /api/usermanagement.
Schema
The user management schema is available at /api/schema/usermanagement/managementrequest.xsd
Create
In order to create a user the create tag needs to be sent containing the username, surname, course and role at the minimum.
<?xml version="1.0" encoding="utf-8"?>
<userManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/usermanagement/managementrequest.xsd">
<create id="str1234">
<username>test</username>
<surname>testy</surname>
<role>Student</role>
<course>test</course>
<modules>
<moduleid id="dfdsf">2</moduleid>
</modules>
</create>
</userManagementRequest>
If the operation is successful the response returns the id of the created user in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<userManagementResponse>
<create id="str1234">
<id>1133</id>
<status_code>100</status_code>
<status>OK</status>
</create>
</userManagementResponse>
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<userManagementResponse>
<create id="str1234">
<id></id>
<status_code>703</status_code>
<status>User not created</status>
</create>
</userManagementResponse>
Update
In order to update a user the update tag needs to be sent containing an id tag of the user to be updated.
<?xml version="1.0" encoding="utf-8"?>
<userManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/usermanagement/managementrequest.xsd">
<update id="str1234">
<id>1133</id>
<surname>testy2</surname>
</update>
</userManagementRequest>
If the operation is successful the response returns the id of the updated user in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<facultyManagementResponse>
<update id="str1234">
<id>1133</id>
<status_code>100</status_code>
<status>OK</status>
</update>
</facultyManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<userManagementResponse>
<update id="str1234">
<id></id>
<status_code>702</status_code>
<status>User not updated</status>
</update>
</userManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | update | The id used to identify the user to update | Only used when updating |
| username | create/update | a unique username | On creation |
| surname | create/update | the users surname | On creation |
| role | create/update | the users role i.e. Student | On creation |
| title | create/update | the users title | No |
| forename | create/update | first name of the user | No |
| initials | create/update | initials for the user | No |
| create/update | the users unique email address | No | |
| password | create/update | password for the user if not using ldap | No |
| course | create/update | the course the student is studying / staff type | No |
| gender | create/update | gender of the user | No |
| year | create/update | the current year the student is studying | No |
| studentid | create/update | a student id from an external SMS | No |
| modules | create/update | The modules the user is enrolled on | No |
Delete
In order to delete a user the delete tag needs to be sent containing an id tag of the user to be deleted.
<?xml version="1.0" encoding="utf-8"?>
<userManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/usermanagement/managementrequest.xsd">
<delete id="str1234">
<id>1133</id>
</delete>
</userManagementRequest>
If the operation is successful the response returns the id of the deleted user in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<userManagementResponse>
<delete id="str1234">
<id>1133</id>
<status_code>100</status_code>
<status>OK</status>
</delete>
</userManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<userManagementResponse>
<delete id="str1234">
<id></id>
<status>User does not exist</status>
</delete>
</userManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | delete | The id used to identify the user to delete | Only used when updating |
Response Codes
Possible response codes are as follows:
| Code | Description |
|---|---|
100 | Action successfully performed |
| 700 | Error when deleting user |
| 701 | User does not exist |
| 702 | Error when updating user |
| 703 | Error when creating user |
| 704 | User not deleted as in use |
| 705 | Course does not exist |
| 706 | User already exists |
| 707 | Invalid user role |
| 708 | Nothing to update |
Notes 1 - Roles
The only valid roles are as follows:
| Students | Staff Members |
|---|---|
| Student | Staff |
| Graduate | Inactive Staff |
| Left |
Students are assigned to a course, Staff members use the course field to assign there type. The supported staff types are as follows:
| University Lecturer |
| NHS Lecturer |
If you are looking to change a student user to a staff user via the API (or vice-versa) then it is important to also supply the course.
Notes 2 - Modules
The current functionality of the usermanagement API is to only enrol users onto modules that have been provided in the modules element. No un-enrolment takes place. The reasoning behind this is that the usermanagement API is to be used as the initial creation/upadte of the users before the churn of an academic year starts. Once the churn starts the modulemanagement/enrol api should be used as this is more efficient at enrolling and un-enrolling users.
Handler
All module management requests should hit /api/modulemanagement/enrol.
Schema
The user enrolment schema is available at /api/schema/modulemanagement/enrolrequest.xsd
Enrol
In order to enrol a user onto a module the module id, user id and user attempt must be provided (the academic session is considered to be the current session unless provided).
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementEnrolRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/modulemanagement/enrolrequest.xsd">
<enrol id="str1234">
<userid>119</userid>
<moduleid>3</moduleid>
<attempt>3</attempt>
</enrol>
</moduleManagementEnrolRequest>
If the operation is successful the response returns the id of the enrolment in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementEnrolResponse>
<enrol id="str1234">
<id>38</id>
<status_code>100</status_code>
<status>OK</status>
</enrol>
</moduleManagementEnrolResponse>
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 enrol requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementEnrolResponse>
<enrol id="str1234">
<id></id>
<status_code>507</status_code>
<status>User does not exist</status>
</enrol>
</moduleManagementEnrolResponse>
Un-enrol
In order to un-enrol a user onto a module the module id and user id must be provided (the academic session is considered to be the current session unless provided).
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementEnrolRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/modulemanagement/enrolrequest.xsd">
<unenrol id="str1234">
<userid>119</userid>
<moduleid>3</moduleid>
<session>2016</session>
</unenrol>
</moduleManagementEnrolRequest>
If the operation is successful the response returns the id of the enrolement in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementEnrolResponse>
<unenrol id="str1234">
<id>38</id>
<status_code>100</status_code>
<status>OK</status>
</unenrol>
</moduleManagementEnrolResponse>
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 enrol requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<moduleManagementEnrolResponse>
<unenrol id="str1234">
<id></id>
<status_code>507</status_code>
<status>User does not exist</status>
</unenrol>
</moduleManagementEnrolResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| userid | enrol/unenrol | The rogo user id to enrol/unenrol to/from a module | Yes |
| moduleid | enrol/unenrol | the rogo module id to enrol/unenrol to/from | Yes |
| session | enrol/unenrol | The academic year the enrolment is for | For unenrol |
| attempt | enrol/unenrol | The users attempt at this module | When enrolling |
Response Codes
Possible response codes are as follows:
| Code | Description |
|---|---|
100 | Action successfully performed |
| 507 | Invalid user |
| 508 | Error enrolling user |
| 509 | Error unenrolling user |
| 510 | Invalid academic session supplied |
| 514 | User already enrolled |
Notes
The enrolment API only enrols users onto modules as students.
Handler
All assessment management requests should hit /api/assessmentmanagement.
Schema
The user management schema is available at /api/schema/assessmentmanagement/managementrequest.xsd
Create
In order to create an assessment the create tag needs to be sent containing the title, type, owner, session, start date, end date and modules at the minimum.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/assessmentmanagement/managementrequest.xsd">
<create id="str1234">
<title>test</title>
<type>Formative</type>
<owner>1</owner>
<session>2016</session>
<startdatetime>2016-05-30T09:00:00</startdatetime>
<enddatetime>2016-05-30T10:00:00</enddatetime>
<modules>
<moduleid id="dfdsf">2</moduleid>
</modules>
</create>
</assessmentManagementRequest>
If the operation is successful the response returns the id of the created assessmentin the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementResponse>
<create id="str1234">
<id>1133</id>
<status_code>100</status_code>
<status>OK</status>
</create>
</assessmentManagementResponse>
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementResponse>
<create id="str1234">
<id></id>
<status_code>215</status_code>
<status>Paper type unknown</status>
</create>
</assessmentManagementResponse>
Update
In order to update an assessment the update tag needs to be sent containing an id tag of the assessment to be updated.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/assessmentmanagement/managementrequest.xsd">
<update id="str1234">
<id>1133</id>
<title>testy2</title>
</update>
</assessmentManagementRequest>
If the operation is successful the response returns the id of the updated assessment in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementResponse>
<update id="str1234">
<id>1133</id>
<status_code>100</status_code>
<status>OK</status>
</update>
</assessmentManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementResponse>
<update id="str1234">
<id></id>
<status_code>206</status_code>
<status>Assessment title is already in use</status>
</update>
</assessmentManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | update | The id used to identify the assessment to update | Only used when updating |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
| externalsys | create/update | The name of the external system | If using the externalid as your primary identifier instead of id |
| title | create/update | The title of the assessment | on creation |
| type | create | The type of assessment | create only |
| owner | create/update | The owner of the assessment within Rogo | on creation |
| session | create/update | The academic year the assessment is run in | on creation |
| startdatetime | create/update | The start time of the assessment | on creation |
| enddatetime | create/update | The end time of the assessment | on creation |
| modules | create/update | The modules the assessment is run under | on creation |
| timezone | create/update | The timezone the assessment will be taken in | no |
| duration | create/update | The duration of the assessment | no |
| labs | create/update | The labs the assessment will be taken in | no |
Delete
In order to delete a assessment the delete tag needs to be sent containing an id tag of the user to be deleted.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/assessmentmanagement/managementrequest.xsd">
<delete id="str1234">
<id>1133</id>
</delete>
</assessmentManagementRequest>
If the operation is successful the response returns the id of the deleted assessment in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementResponse>
<delete id="str1234">
<id>1133</id>
<status_code>100</status_code>
<status>OK</status>
</delete>
</assessmentManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementResponse>
<delete id="str1234">
<id></id>
<status_code>202</status_code>
<status>Paper does not exist</status>
</delete>
</assessmentManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| id | delete | The id used to identify the assessment to delete | yes |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
Schedule
In order to schedule an assessment the schedule tag needs to be sent containing the owner, title, duration, session and month at a minimum.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://localhost/rogo/api/schema/assessmentmanagement/managementrequest.xsd">
<schedule id="str1234">
<owner>1</owner>
<title>test</title>
<session>2016</session>
<duration>60</duration>
<month>1</month>
<modules>
<moduleid id="dfdsf">2</moduleid>
</modules>
</schedule>
</assessmentManagementRequest>
If the operation is successful the response returns the id of the scheduled assessment in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 schedule requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementResponse>
<schedule id="str1234">
<id>1133</id>
<status_code>100</status_code>
<status>OK</status>
</schedule>
</assessmentManagementResponse>
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 schedule requests, meaning we need to be able to identify the response to the specific request.
<?xml version="1.0" encoding="utf-8"?>
<assessmentManagementResponse>
<schedule id="str1234">
<id></id>
<status_code>214</status_code>
<status>This system is set-up to only allow the scheduling of summative exams</status>
</schedule>
</assessmentManagementResponse>
Valid attributes
| Attribute | Action | Info | Required? |
|---|---|---|---|
| title | schedule | The title of the assessment | yes |
| owner | schedule | The owner of the assessment within Rogo | yes |
| session | schedule | The academic year the assessment is run in | yes |
| modules | schedule | The modules the assessment is run under | yes |
| duration | schedule | The duration of the assessment | yes |
| month | schedule | The month we would like to schedule in | yes |
| cohort_size | schedule | Size of cohort | Yes |
| sittings | schedule | How many sittings are required | no |
| barriers | schedule | Are barriers required in the exam room | no |
| notes | schedule | Misc notes | no |
| campus | schedule | Request campus to run the assessment on | no |
| externalid | create/update | The external is used to identify the module | If using the externalid as your primary identifier instead of id |
| externalsys | create/update | The name of the external system | If using the externalid as your primary identifier instead of id |
Response Codes
Possible response codes are as follows:
| Code | Description |
|---|---|
100 | Action successfully performed |
200 | Undefined error |
| 201 | Error deleting paper |
| 202 | Paper does not exist cannot delete |
| 203 | Paper not deleted as in use |
| 204 | Error creating paper |
| 205 | Error scheduling paper |
| 206 | Invalid paper title |
| 207 | Invalid paper owner |
| 208 | Invalid user role |
| 209 | Invalid academic session |
| 210 | Paper doesn not exist cannot update |
| 211 | Invalid modules supplied |
| 212 | Invalid start/end date supplied |
| 213 | Error updating paper |
| 214 | Cannot create summative paper as centrally controlled |
| 215 | Invalid paper type supplied |
| 216 | Nothing to update |
| 217 | External ID already in use |
Filter by assessment
Handler
Gradebook requests for a specific paper should hit /api/gradebook/paper/<id>.
<?xml version="1.0" encoding="utf-8"?>
<gradebookResponse>
<assessment id="<id>">
<gradeitem>
<userid>1</userid>
<username>test</username>
<raw_grade>40</raw_grade>
<adjusted_grade>30</adjusted_grade>
<classification>Fail</classification>
</gradeitem>
...
</assessment>
</gradebookResponse>
Filter by module
Handler
Gradebook requests for a specifc module should hit /api/gradebook/module/<id>.
<?xml version="1.0" encoding="utf-8"?>
<gradebookResponse>
<module id="<id>">
<assessment id="1234">
<gradeitem>
<userid>1</userid>
<username>test</username>
<raw_grade>60</raw_grade>
<adjusted_grade>55</adjusted_grade>
<classification>Pass</classification>
</gradeitem>
...
</assessment>
..
</module>
</gradebookResponse>
If there is an error performing and of the above operations the response message returns null in the id node and a message in the status node. The create tags id attribute is returned in order to match up its request with the response.
<?xml version="1.0" encoding="utf-8"?>
<gradebookResponse>
<gradebook id="1234">
<id></id>
<status>Gradebook not found for module 1234</status>
</unenrol>
</gradebookResponse>
External Systems
External system need to be provided with external id in all calls.
API clients can now be associated with an external system. It is expected only a sys admin user would not be associated with a specific external system.
XSDs
XSDs for each webservice are located at /api/schema.
Media Types
Supported media types:
- text/xml
Authentication
In order to use the web services defined in the API you must be authenticated. Authentication is achieved via Oauth2.Rogo uses the bshaffer php library.
The steps to get an authorisation key are as follows:
Sysadmin users can add clients and specify the web services they will be authorised to use.
Once the client has been added the external client then needs to visit the following page on Rogo. e.g.
https://<your rogo server>/api/authorise.php?response_type=code&client_id=<your client id>&state=<random string>
The ‘state’ parameter is intended to preserve some state object set by the client in the Authorization request, and make it available to the client in the response. The main security reason for this is to stop Cross Site Request Forgery (XRSF).
An example of this would be a hash of the session cookie or a random value stored in the server linked to the session.
Client is required to login as user linked to the client account created in step 1.
The logged in user will then be asked to authorise the access rights given in step 1 to the client.
An authorisation token will then be generated and returned to the client, for example:
https:///www.example.com?code=a40c0bda3ec51090de84818263039c985f0a44e1&state=xyz
If the client verifies the ‘state’ value returned then it will reject authentication responses that were generated as the result of requests by third party attackers trying to log the user in in the background without the user’s knowledge.
Client site then uses Authorisation code to request access token, for example the request:
curl -u <your client id>:<your secret key> https://<your rogo server>/api/requesttoken -d grant_type=authorization_code -d code=a40c0bda3ec51090de84818263039c985f0a44e1
Would get a response like:
<?xml version="1.0"?>
<response>
<access_token>2bfbfd8a0d3d2b93bf37a1472a413ed3e1a1d80c</access_token>
<expires_in>1209600</expires_in>
<token_type>Bearer</token_type>
<scope/>
<refresh_token>9224f41003b7195e306bf9d8fa050b7124bf040d</refresh_token>
</response>
The access token can then be used to access web services until expiry. The refresh token can be used to refresh Access token until expiry.
From now on you can generate new access and refresh token using your current refresh token (saves you having to login an authorise again):
curl -u <your client id>:<your secret key> https://<your rogo server>/api/requesttoken -d grant_type=refresh_token -d refresh_token=9224f41003b7195e306bf9d8fa050b7124bf040d
The client can then call the web services with access token in a POST request, for example:
curl -k https://<your rogo server>/api/coursemanagement?access_token=f35371fc284defeaf3f1d273f73e992a8ce74fc4 -H "Content-Type:text/xml" -d "<courseManagementRequest xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
xsi:noNamespaceSchemaLocation=\"https://localhost/api/schema/coursemanagement/managementrequest.xsd\">
<create id=\"str1234\">
<name>rogotest</name>
<description>rogo test</description>
<school>test</school>
<faculty>test</faculty>
</create>
</courseManagementRequest>"
Configuration
The following config settings can be found in the rogo configuration screen:
cfg_enable_api | Enables or disables the API functionality |
api_oauth_access_lifetime | Stores in seconds the lifetime of an oauth access token |
api_oauth_refresh_token_lifetime | Stores in seconds the lifetime of an oauth refresh token |
api_oauth_always_issue_new_refresh_token | Enables or disables the oauth refresh token |
api_allow_superuser | Allow sys admin users to access all available external systems 6.5.0 onwards. |
Developer Tools
Logging of all API requests and responses can be enabled by added the apilogfile config item in the configuration screen via the 'apilogfile' setting
Logging is only suggested for development servers as it will chew through your disk space.