ROGO 6.1.0

Web services

The following restful endpoints are available:

Module management

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.

Create Request

<?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.

Create Response

<?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.

Create Error Response

<?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.

Update Request

<?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.

Update Response

<?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.

Create Error Response

<?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.

Delete Request

<?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.

Delete Response

<?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.

Create Error Response

<?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

School management

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.

Create Request

<?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.

Create Response

<?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.

Create Error Response

<?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.

Update Request

<?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.

Update Response

<?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.

Create Error Response

<?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.

Delete Request

<?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.

Delete Response

<?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.

Delete Error Response

<?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

Course management

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).

Create Request

<?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.

Create Response

<?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.

Create Error Response

<?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.

Update Request

<?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.

Update Response

<?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.

Create Error Response

<?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.

Delete Request

<?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.

Delete Response

<?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.

Delete Error Response

<?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

Faculty management

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.

Create Request

<?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.

Create Response

<?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.

Create Error Response

<?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.

Update Request

<?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.

Update Response

<?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.

Create Error Response

<?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.

Delete Request

<?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.

Delete Response

<?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.

Delete Error Response

<?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

User management

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.

Create Request

<?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.

Create Response

<?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.

Create Error Response

<?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.

Update Request

<?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.

Update Response

<?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.

Create Error Response

<?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
email	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.

Delete Request

<?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.

Delete Response

<?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.

Delete Error Response

<?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.

Module Enrolment

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).

Create Request

<?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.

Create Response

<?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.

Create Error Response

<?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).

Create Request

<?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.

Create Response

<?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.

Create Error Response

<?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.

Assessment management

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.

Create Request

<?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.

Create Response

<?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.

Create Error Response

<?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.

Update Request

<?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.

Update Response

<?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.

Create Error Response

<?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.

Delete Request

<?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.

Delete Response

<?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.

Delete Error Response

<?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.

Schedule Request

<?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.

Schedule Response

<?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.

Schedule Error Response

<?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

Gradebook

Filter by assessment

Handler

Gradebook requests for a specific paper should hit /api/gradebook/paper/<id>.

Gradebook filer by assessment response

<?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>.

Gradebook filer by module response

<?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.

Gradebook Error 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:

1. Add an Oauth Client

Sysadmin users can add clients and specify the web services they will be authorised to use.

2. Request Authorisation

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.

3. Request Access and Refresh Tokens

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

4. Web Services

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

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.

Frameworks

The following frameworks are used in the api code:

Slim - php api framework
Twig - php template engine

API

ROGO 6.1.0

Web services

Handler

Create

Update

Valid attributes

Delete

Valid attributes

Response Codes

Handler

Create

Update

Valid attributes

Delete

Valid attributes

Response Codes

Handler

Create

Update

Valid attributes

Delete

Valid attributes

Response Codes

Handler

Create

Update

Valid attributes

Delete

Valid attributes

Response Codes

Handler

Create

Update

Valid attributes

Delete

Valid attributes

Response Codes

Notes 1 - Roles

Notes 2 - Modules

Handler

Enrol

Un-enrol

Valid attributes

Response Codes

Notes

Handler

Create

Update

Valid attributes

Delete

Valid attributes

Schedule

Valid attributes

Response Codes

Filter by assessment

Handler

Filter by module

Handler

External Systems

XSDs

Media Types

Authentication

Configuration

Developer Tools

Related content