SurpassLocal - TestSession Resource
When a test has been scheduled and has become locked, the SurpassLocal API can be used to update the test session state. This may be necessary if the invigilator wishes to pause, resume, unlock or void a test via an external system. The test can be identified by its ID or by its unique keycode in Surpass.
TestSession Resource
Below we have listed the operations, http verbs and an example URL for the TestSession resource within the SurpassLocal API.
|
Operation |
HTTP Verb |
Example URL |
|
List |
GET |
https://...surpass.com/api/v1/TestSession/ |
|
Read (individual by ID) |
GET |
https://...surpass.com/api/v1/TestSession/123 |
|
Read (individual by keycode) |
GET |
https://...surpass.com/api/v1/TestSession/H76RBD8P |
|
Update by id |
PUT |
https://...surpass.com/api/v1/TestSession/1 |
|
Update by keycode |
PUT |
https://...surpass.com/api/v1/TestSession/H76RBD8P |
Attributes for the TestSession Resource
Within the table below we have provided all of the attributes included in the test session 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 |
Notes |
Unique Identifier |
|
Id |
Int |
Unable to PUT |
X |
|
reference |
String |
This is the unique keycode generated in Surpass. |
X |
|
href |
String |
Unable to PUT |
|
|
testState |
String |
It is only possible to change state: |
|
|
voidReason |
String | Possible values: |
|
|
voidMessage |
String |
Required when voidReason is Other. |
|
|
useExternalReference |
String |
Additional information about the candidate, |
|
GET Request and Return
The GET TestSession resource can be called directly by browsing to the URL, any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the TestSession resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response; this is detailed in the page understanding the Surpass API.
Example GET request & response (JSON)
Example GET request & response (XML)
PUT Request and Return
PUT Requests should reference the ID or Reference within the resource. The resource being updated should be included in the body of the request and can be sent in either JSON or XML format. Only the field you want to be updated needs to be included within the request all others can be omitted; these fields will retain their current values. The content-length, content-type and Authorization will also be required in the header of the request.
Example PUT request & response (JSON)
Example PUT request & response (XML)
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 SurpassLocal API can be found here.
Filtering results on Resource objects
The GET TestSession method allows you to filter on resource objects contained within the TestSession Resource.
You can filter on the date the test session was last modified, for example through a state change or interaction:
https://...surpass.com/api/v1/TestSession/?$filter=modifiedDate ge 2019-04-29T10:20:00Z
Or you can filter by the date range of the test session:
https://...surpass.com/api/v1/TestSession/ TestSession?$filter=enddate ge 2019-04-22T00:00:00Z and startdate le 2019-04-27T00:00:00Z
Required Permissions
To successfully call the methods in the Surpass Local TestSession Resource, the user validating the requests must exist within BTL’s CMS system. If you require a password reminder or a new account to be created, send a request to the BTL Service Desk (support@btl.com).