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 |