TestSchedule Resource

Within Surpass test schedules are the exams that are due to take place in the Surpass system. A test schedule must have a candidate, centre, test and start/end date/time assigned to it. Within the user interface this maps to the 'Schedule' screen in 'Test Administration', a POST request adds a single schedule to this screen.  


The Surpass API  also offers the ability to automatically associate candidates to a centre and subject at the point of scheduling. This allows for a simplified scheduling process. This is especially useful if it is unknown what tests the candidate may be taking when the candidate is first created in Surpass. It is important to note that the association between the centre and subject must already exist before sending a POST TestSchedule request.

TestSchedule Resource

Below we have listed the operations, http verbs and an example URL for the TestSchedule resource within the Surpass API. 

Operation HTTP Verb Example URL
Create POST https://...surpass.com/api/v2/TestSchedule
Delete by ID DELETE https://...surpass.com/api/v2/TestSchedule/1
Delete by Keycode DELETE https://...surpass.com/api/v2/TestSchedule/{keycode}
Attributes for the TestSchedule Resource

Within the table below we have provided all of the attributes included in the test schedule resource. This includes the attribute name, data type and if the attribute is mandatory when sending a POST request. Remember that if an attribute is not mandatory, it can be omitted from the body of the POST request.
Attribute Name Type Description Default Value
(POST)
Mandatory for Create (POST)
Test Resource The test that is being scheduled. If no test form is selected the system will automatically select the test form. ID or reference can be used. - X
Centre Resource The centre where the exam will be taken. ID or reference is allowed. - X
Candidate Resource The candidate that is being scheduled for the test. Only a single candidate can be included in the request using ID or reference. -
startDate Date The date for the exam window to begin. DD/MM/YYYY - X
endDate Date The date for the exam window to end. DD/MM/YYYY - X
startTime Time The start time of the window in which the exam can be taken within the date range specified above. TTTT - X
endTime Time The end time of the window in which the exam can be taken within the date range specified above. TTTT - X
reasonableAdjustments Object (see below) -
markedExternally Boolean Optional value that flags an exam to be marked externally. When 'true', a completed test will bypass marking and move to the 'markedExternally' warehouse state in Surpass. Defaults to ‘false’ when omitted. false
allowMultipleOpenSessions Boolean This will override Surpass logic to schedule a test even if the candidate has an open test schedule. false
requiresInvigilation Boolean Invigilated exams require a PIN or to be ‘unlocked’ by an invigilator during delivery. This is an optional attribute that defaults to the setting in Test Creation if it is omitted. configured on test
testTags Collection,
String values
Multiple tags are allowed. Allocated tags will display in invigilation screen within the ‘Tags’ column. Max string length of 250. null
TestForm Resource The test that is being scheduled. If no test form is selected the system will automatically select the test form. ID or reference can be used. automatic selection
Marker Resource The marker who will be assigned to the test once completed. You can supply either the id (int) or the reference (string) for the user. X (if enabled at Test level)
Moderator Resource The moderator who will be assigned to the test once completed. You can supply either the id (int) or the reference (string) for the user. X (if enabled at Test level)
purchaseOrder String This is only mandatory if this has been turned on in Site Settings in Surpass. Stores an external invoice number against the test session. - X
(if enabled)
breakReasonableAdjustments Object (see below) -
Subject Resource The Subject that the test belongs to. This is not mandatory but allows test references across subjects to not have to be unique. ID or reference is allowed. -
unscheduledBreak Resource Set an unscheduled break per candidate, meaning a candidate can choose when to take a break throughout their test. The time is set in minutes. If set to '0' the candidates will receive no break time. -
language String The language that the test will be delivered in. configured on test
enforceTimes Boolean Whether or not you add the 12 hour buffer to your start date and end date window. This is only mandatory if enabled in Site Settings. false X

Reasonable Adjustments object
Attribute Name Type Description
extraTimeMin Int The time allocated as additional test time to the candidate in minutes. Optional. If both extraTimePercentage and extraTimeMin are included within the request, extraTimeMin will take priority. Max 999 minutes.
extraTimePercentage Int The percentage of the overall test time that will be allocated to the candidate as additional test time. Optional. If both extraTimePercentage and extraTimeMin are included within the request, extraTimeMin will take priority.
reason String The reason for allocating any additional time to the candidate.

Break Reasonable Adjustments object
Attribute Name Type Description
extraTimeMin Int The time allocated as additional break time to the candidate in minutes. Max 999 minutes. Both section and unscheduled breaks supported.
extraTimePercentage Int The percentage of the overall break time that will be allocated to the candidate as additional break time. If both extraTimePercentage and extraTimeMin are included within the request, extraTimeMin will take priority. Both section and unscheduled breaks supported.
numberOfExtraBreaksPerSection Int If unscheduled breaks are used this property allows you to specify the number of extra breaks allowed per section.
reason String The reason for allocating any additional break time to the candidate.
Additional Notes

  • When creating tests in the Surpass system ensure that the Test Reference and Subject Reference are unique. This can be changed in the Test Creation section of Surpass.
  • The start/end dates and start/end times are independent of each other i.e. The start/end dates mark the available test window and the start/end times are the times in which the test can be delivered on all available dates within that window. 
    e.g. Where startDate is 18/12/2015 , startTime is 0900 , endDate is 21/12/2015 and the endTime is 1700 , the test will be available for delivery on the following dates/times: 
    18/12/2015 09:00 - 17:00, 19/12/2015 09:00 - 17:00, 20/12/2015 09:00 - 17:00, 21/12/2015 09:00 - 17:00 
  • If a test requires invigilation in Test Creation it will not be possible to set the requiresInvigilation property as false in the request and an error message will be provided in the response. 
  • If the site level setting "Test scheduling over multiple days" is disabled then the API will provide an error message if the start date and end date included in the request is more than one day. 
  • If the site level setting "Purchase Order Number for Scheduling" is set to yes then the property "purchaseOrder" is required in the request.

POST Request and Return

The POST TestSchedule method requires the attributes to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.

Depending on how the request was submitted the response will be returned in either JSON or XML format. If the call was unsuccessful then you will receive an error message, all error messages available in the Surpass API can be found here.

An optional header can be included in the request that will automatically associate a candidate with a centre and subject. This header is: autoSyncCentreSubject:true

Example POST request & response (XML)
Example POST request & response (JSON)


DELETE Request and Return
  

DELETE Requests should use the ID or Keycode of the test schedule you want to delete. Successful deletes will return a status of 200 and will return the base resource with all values set to null. An example of the DELETE TestSchedule request has been provided below:

DELETE https://...surpass.com/api/v2/TestSchedule/9596


Required Permissions

To successfully call the POST TestSchedule method the user specified in the header of the request must have the 'Schedule Test' permission in Surpass and be associated to the relevant centre and subject that is contained within the request. Additionall to specify a test form the user must have the "Reveal Test Forms" permission and to specify reasonable adjustments the user must have the "Schedule extra time for tests with strict control for reasonable adjustments"

Feedback and Knowledge Base