Test Schedule Resource R12.11

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 assigned to the test session. This is predominantly used in computer based projects. For this property to be included within the request the test has to be setup to enable user associations and markers in Test Creation. The reference or id of a user is required. -
moderator Resource The moderator assigned to the test session. This is predominantly used in computer based projects. For this property to be included within the request the test has to be setup to enable user associations and moderators in Test Creation. The reference or id of a user is required. -
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 object This object allows users to specify unscheduled breaks to a candidates test session. -
unscheduledBreak / extraTimeMin integer The number of minutes to be allocated to a candidates unscheduled break -
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.

Feedback and Knowledge Base