Exporting Candidate Interactions

In Surpass it is possible to enable delivery interaction logging for each test session, this records exactly what the candidate has done in the delivery engine so this information can be used in candidate appeals or investigations. This is a test level setting in Test Creation in Surpass and is currently only available to export via the Surpass API. It is also worth noting that this logging will only take place if the test has been delivered via the SecureClient, information will not be available for tests delivered using the web delivery address.



Request URL

To request the candidate interaction information the request URL should be built as follows:

https://...surpass.com/Result/{keycode}/CandidateInteractions/
https://...surpass.com/Result/{id}/CandidateInteractions/  

Interactions can only be requested for an individual keycode or id. If this information is required for more than one candidate test session then separate requests would need to be sent to the Surpass API specifying each keycode or id.

Properties for Candidate Interactions on Results

The table below provides all properties that are returned when requesting candidate interactions for a particular result. This includes the property name, type and description.
Property Name Type Description
id int The unique id of the result the candidate interactions applies to
href string The URL to the candidate interactions for a specific keycode
reference string The keycode for the result the candidate interactions applies to
interactions collection A collection of specific interactions logged during candidate delivery
interactions / type enumeration The type of interaction performed during delivery
interactions / data string The details of the interaction
interactions / time dateTime The time of the interaction
interactions / itemId string The item the interaction is associated to, if it is relevant.
Interpreting the Candidate Interactions

The interaction type and data properties returned by the candidate interactions API response can vary and need to be interpreted to get the full use out of this export. Below we have provided a table that describes each type of interaction returned and a description and example of the data property. 
Interaction Type Data Description
MCQ Selection If a selection is made on an MCQ, MRQ or Either / Or question type the data property will return the option and component that was selected. This will be the specific option selected in the delivery engine rather than the order the question was authored in, which could be different if the answer options are randomised. Changes are logged every 5 seconds and in the event of changing questions, only modifications will be tracked. Below is an example data response:

<data>Selected Answers:Scene Id: 1 Component Id:4 Item Id:2 B</data>
Gap Fill If a gap fill is interacted with in the delivery engine the component id and character length will be returned in the data response. The interaction collection will also return the item id. It is important to remember that the gap fill type relates to Numerical Entry, Essay and Short Answer question types. Changes are logged every 5 seconds and in the event of changing questions, only modifications will be tracked. Below is an example data response:

<data>Selected Answers:Scene Id: 1 Component Id:4 Item Id:1 Chars Length:15 Formatted Length:15</data>
Other Question Interactions with non supported question types are identified by the "Other Question" type, this also applies to introduction and information pages. Changes are logged every 5 seconds and in the event of changing questions, only modifications will be tracked. Below is an example data response:

<data>SomeThing Changed</data>
Button Clicked Every interactive button in the Surpass delivery engine is labelled so the consumer of the API method can identify the time a button was selected. If the next button is selected the data will display "m_nextBtn" followed by the Section and Question number that will be loaded, equally all buttons on the navigation bar are identified by "BreadcrumbButton" followed by the Section and question number. All other buttons can be identified by the label and name. Each button click has a recorded time stamp to assist the consumer. Below we have provided examples of this:

<data>Button:@Name=CSelfSizingButton1349@Id=m_startButton@Label=Start Exam</data>

<data>m_nextBtn Section:S1 Question:1</data>
Dialog Opened If a dialog window is opened an interaction will be logged. The data returned will include the title of the dialogue window and the message returned to the candidate to help identify what was displayed to the candidate. A time stamp will be logged when this happened. An example has been provided below:

<data>CConfirmDialog8739 Title:Confirm Finish Label:Finish Message:You have not attempted all of the questions in this exam, and some have been flagged.\r\n\r\nAre you sure you would like to finish?</data>
Dialog Closed If a dialog window is closed an interaction is logged. The data returned will include the title of the diaglogue window and the message returned to the candidate to help identify what was displayed to the candidate. The data will be almost identical to the dialog opened type. An example has been provided below:

<data>CConfirmDialog8739 Title:Confirm Finish Label:Finish Message:You have not attempted all of the questions in this exam, and some have been flagged.\r\n\r\nAre you sure you would like to finish?</data>
Tool Opened In Surpass Item Authoring source material can be attached to questions to help assist the candidate with the question or provide vital information in order to answer the question. Surpass supports authors to upload images, videos, audio, PDF files and flash files as source material. Videos, audio and PDF used in this format is launched using the native player on the delivery machine however images and flash files added as tools. This interaction type identifies if a tool has been opened by the candidate. Below we have provided an example of the data returned:

<data>CToolPopupSpark5404 ToolName:Calculator</data>
Tool Closed This type identifies if a tool has been closed by the candidate. Below we have provided an example of the data returned:

<data>CToolPopupSpark5404 ToolName:Calculator</data>
Submitted Exam Once the candidate has completed their test and the selected the finish button and the confirmation buttons the interaction logs will identify this using the type "Submitted Exam" this test will now be unavailable to access and will be sent to Surpass central when there is a valid connection. Example data response:

</data>
PUV Paused, unpaused and voided (PUV) relates to invigilator controls that can be performed and displayed to a candidate during the test. This is not an action of the candidate but is logged as it can be useful information for candidate appeals. The data property highlights the type of PUV i.e Paused, UnPaused, Void. Below we have provided an example data property:

<data>Exam Paused</data>
Keycode Validated To start a test in Surpass the keycode must be entered, the event type "key code validated" identifies that the keycode has been entered by the candidate/invigilator/external system and confirmed as a valid keycode. The candidate will then be taken to the confirm details screen prior to taking the test. An example data property has been provided below:

<data>keyCode success: MCXDKG7L</data>
Exam Script Downloaded Once the keycode has been validated and the exam script may need to be downloaded (unless this is done prior) the interaction logs capture this information using this event type. Below we have provided an example data property:

<data>success</data>
All Items Downloaded Prior to starting the test the SecureClient checks the test structure and ensures all items are downloaded and have the relevant files. This interaction is also captured. Below is an example data property:

<data>success</data>
Pin Entered If a test has been setup to require invigilation then the candidate will have to enter a PIN or wait until the invigilator unlocks the test for the candidate. If a PIN is required and entered this is logged in the candidate interactions. An example has been provided below:

<data>Pin Number: 3G6M8J, success</data>
Dirty Data Sent to The Server To ensure resilience the SecureClient has a feature to synchronise its exam responses back to Surpass Central/Local in case the candidate needs to move machines during a test session. All these requests are encrypted and unreadable. The interaction log identifies if the SecureClient is sending these requests and that it is successful. An example response has been provided below:

<data>success</data>
Resilience Mode The SecureClient has built in functionality that stores candidate responses in the local database in case of a loss of internet that we refer to as resilience mode. If a connection is lost during the test the SecureClient will identifiy this and start storing responses locally only. The interaction logs highlight this, if the value if "OFF" this means the SecureClient can successfully send data to Surpass central. If this is "ON" this means the SecureClient is working offline. An example of the data response has been provided below:

<data>Resilience Mode OFF</data>
Strike through The Surpass delivery engine provides the ability to strike through multiple choice answer options to assist the candidate during the test session. Each time this happens a interaction is logged with a time stamp. An example has been provided below:

<data><event typ=\"114\" id=\"5001P142\" optionId=\"2\" associatedCharacter=\"B\" /></data>
Remove strike through An interaction is logged for everytime this is removed as well. An example data response has been provided below:

<data><event typ=\"115\" id=\"5001P142\" optionId=\"2\" associatedCharacter=\"B\" /></data>

GET Request and Return 

Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting Candidate Interactions form the Surpass API

Example GET request & response (JSON)

Example GET request & response (XML)

Required Permissions 

To successfully call this method, the user specified in the header of the request must have the 'View Results' permission for the Subject and Centre associated to the result.  


Feedback and Knowledge Base