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

Notes

Unique Identifier

Id

Int

Unable to POST/PUT

X

reference

String

This is the unique keycode generated in Surpass.

X

href

String

Unable to POST/PUT

 

testState

String

It is only possible to change state:
InProgress > Paused

Paused > InProgress

Ready, LockedByPin, LockedForInvigilator, Paused, InProgress > Voided

 

voidReason

String

Possible values:
Absent, Withdrawn, PartiallyCompleted, Other.
Not required - Auto will be used when not specified.

 

voidMessage

String

Required when voidReason is Other.

 


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.

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

 

Feedback and Knowledge Base