HistoricalResult Resource

Within the Surpass API there a several different concepts of results that are available at different stages of the assessment journey, each of these have been explained below:

Result - This is a submitted, marked and moderated test session that is available within the Test Administration screen in Surpass. Later this result is exported to our reporting interface where further rescoring and scale scoring changes can take place. The result resource will not return data that has been modified in reporting and will always return the latest information available within Test Administration.

AnalyticsResult - This result is the latest version of a result in the reporting interface. If any changes have taken place in Reporting this resource will provide you with the tools to extract the latest result data from Surpass.

HistoricalResult - This resource allows a system to consume all versions of results that have been manipulated within Reporting. It might be that a particular result is modified several times meaning it has different versions. The Historical result resource provides a method of auditing and consuming all versions of a particular result.

Each resource is mirrored where possible with additional properties being returned in AnalyticsResult and HistoricalResult. They contain all of the information regarding a single candidate’s completed exam session. This includes all of the low-level detail of the exam including item level response information.

Operation HTTP Verb Example URL
Search and Filter GET https://...surpass.com/api/v2/HistoricalResult/
Read (individual) GET https://...surpass.com/api/v2/HistoricalResult/1
https://...surpass.com/api/v2/HistoricalResult/A1B2C3D4


Properties for the HistoricalResult Resource

In the table below we have provided all of the properties included in the HistoricalResult Resource. This includes: the property name, type, if the property is available to filter when requesting the GET method and the available operators.

Property Name Type Description Filter
(GET)
Available
Operators
(GET)
isLatest boolean This flag identifies if the historical result is the latest and therefore the same as the analytic result.
adjustedGrade string The grade assigned to the historical result after a rescoring event.
changeDetails object An object containing details of any changes to the historical result
changeDetails / type enumeration The latest change to affect the historical result in rescoring.
Available values: "Rescore" "ScaleScore"
changeDetails / dateApplied dateTime The date that the changes took place, this can be useful to poll to find any results that have had a change applied to them. x le, ge
changeDetails / user resource
(object)
The user that applied the change to the historical result
changeDetails / user / id int The id of the user that applied the change to the historical result
changeDetails / user / reference string The reference of the user that applied the change
changeDetails / user / href string The URL to request details of the user that applied the change to the historical result
changeDetails / rescoringRules resource
(object)
Information on the exact rescoring rules that have been applied to the historical result since it was warehoused.
changeDetails / rescoringRules / id int The id of the rescoring rules resource
changeDetails / rescoringRules / href string The URL to request the rescoring rules that have been applied to a particular historical result.
id int The unique id for this result.
href string The URL to request this specific resource.
subject resource The subject the test belongs to. ID and Reference can be used when filtering. x eq
test resource The test that was delivered. ID and Reference can be used when filtering. test that
testForm resource The test form that was delivered. ID and Reference can be used when filtering. x eq
centre resource The centre the test was delivered at. ID and Reference can be used when filtering. x eq
candidate resource The candidate that took the test. ID and Reference can be used when filtering. x eq
keycode string The unique identifier for the test session and used by the candidate to start the test. x eq
mark int The mark achieved for the entire test.
availableMarks int The total number of marks available for a test.
passMark int The mark for the lowest grade boundary set on the test.
passMarkType enumeration The pass mark type that was selected in Test Creation.
Available values: "Percentage" or "Mark".
percentageMark int The mark achieved by a candidate displayed as a percentage.
passPercentage int The percentage required to achieve the lowest grade boundary set on the test.
pass boolean Used to identify if the candidate has passed all sections, learning outcomes and achieved the pass marks stated above.
grade string The grade that the candidate achieved for this result.
startedDate date/time The date/time the test was started. x le, ge
submittedDate date/time The date/time the test was submitted. x le, ge
warehousedDate date/time The date/time the test was warehoused in Test Administration. This is the date the test was released to results/audit after the test was marked and moderated x le, ge
resultReleased boolean Identifies if the test was moderated in Surpass.
resultSampled boolean Identifies if the test was released as a group in moderation.
durationMode string The time settings for the test, will read 'Untimed', 'Timed' or 'Timed Sections'.
isManuallySubmittedInLocal boolean Identifies if the test was manually submitted by SurpassLocal.
scaleScore int The scale score the candidate received for this result.
scaleScoreMapping resource A link to the full scale score mapping that was used for this test.
learningOutcomeThreshold int The sum of marks assigned to a learning outcomes required before Surpass marking logic incorporates learning outcome boundaries into the result of a test. It may be that a Learning outcome only has 1 mark assigned and therefore inappropriate to grade the candidate on this learning outcome until more marks are assigned (threshold value).
learningOutcomeBoundariesApplied boolean Learning outcome boundaries have been applied to this result. They will only affect the result if the marks exceeds the threshold value.
sections collection A collection of sections contained within the test
sections / name string The section name.
sections / mark int The mark achieved within the section.
sections / percentageMark int The mark a candidate achieved for a section represented as a percentage.
sections / availableMarks int Total marks available within the section.
sections / pass boolean Boolean value identifing if the candidate has passed that section.
sections / passMark int The pass mark required to pass the section.
sections / passPercentage int The pass mark required to pass the section represented as a percentage.
sections / passMarkType enumeration The pass mark type that was selected in Test Creation. Values: "Percentage" and "Mark".
sections / viewingTime int The time spent on this particular section of the test.
sections / items collection a collection of items contained within a section.
sections / items / name string The name of an item delivered within a test.
sections / items / version int The version number of the delivered item.
sections / items / mark int The mark achieved by a candidate for that particular item between 0-1.
sections / items / awardedMark int The awarded mark for a particular item.
sections / items / availableMarks int The total number of available marks for an item.
sections / items / viewingTime int The time spent viewing an item.
sections / items / learningOutcome string The learning outcome assigned to a particular item delivered within the test.
sections / items / unit string The unit assigned to a particular item delivered within the test.
sections / items / surpassReference string The unique Surpass reference for the delivered item.
sections / items / nonScored boolean Boolean value that identifies if the item was scored or non scored.
sections / items / type enumeration The type of item delivered.
Available values: "Question" , "Survey"
sections / items / group collection The id and name of the group of items, where applicable.
sections / items / candidateResponse XML The raw XML used to calculate a candidates response.
sections / items / itemComment string Any item comments provided by the candidate during delivery.
sections / items / itemResponse resource The response for an Item in a user friendly model. Only MCQ, MRQ and EitherOr supported. This will provide the URL to retrieve this from the Item Response resource.
learningOutcomes collection A collection of learning outcomes that have been assigned to items within the test.
learningOutcomes / name string The name of the learning outcome assigned to the test
learningOutcomes / pass boolean This flag identifies if the candidate has passed this learning outcome
learningOutcomes / mark int The mark achieved for all items that have this learning outcome assigned.
learningOutcomes / totalMark int The total number of marks for all items that have this learning outcome assigned.
learningOutcomes / percentageMark int The mark achieved for all items that have this learning outcome assigned in percentage format.
learningOutcomes / passPercentage int The pass percentage required for this learning outcome
learningOutcomes / thresholdExceeded boolean This flag identifies if the number of item marks has exceeded the threshold value and therefore counts towards the final result of the test
learningOutcomes / defaultPassMarkApplied boolean This flag identifies if this learning outcomes pass mark uses the default value, if this is false then the test creator defined a custom learning outcome boundary pass mark.
learningOutcomeBoundaries collection A collection of the learning outcome boundaries setup by the test creator.
learningOutcomeBoundaries / isDefault boolean This flag identifies if the learning outcome boundary was setup to use the default pass mark.
learningOutcomeBoundaries / text string The Learning outcome boundary text that was entered in test creation. This value might not match the value on the item if there was a mistake in the authoring / test creation process and therefore not affect the result.
learningOutcomeBoundaries / passPercentage int The pass percentage for this leanring outcome boundary.
Additional Notes

  • When filtering historical results you can use the same attribute twice for date fields such as “warehousedDate” this allows you to search between two dates. The format for this request would be as follows: https://...surpass.com/api/v2/HistoricalResult?$filter=warehousedDate ge 08/06/2015T00:00:00 and warehousedDate le 09/06/2015T00:00:00
                                                                                                     

GET HistoricalResult Request and Return

The HistoricalResult Resource can be called directly by browsing to the URL. Any parameters such as markedExternally, $filter, $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 HistoricalResult 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)

 
Filtering HistoricalResults on Resource objects

The GET HistoricalResult method allows you to filter on resource objects contained within the HistoricalResult Resource. Subjects, centres, tests, test forms and candidates for that exam session are returned within a standard result response. When filtering on these attributes, you need to additionally specify what attribute we are searching on within that resource, so this is built differently to other attributes contained within the Result Resource. Below we have provided some examples of how these requests are built:

https://...surpass.com/api/v2/HistoricalResult?$filter=subject/reference eq 'subject ref 1' and centre/reference eq 'centre ref 1’

https://...surpass.com/api/v2/HistoricalResult?$filter=subject/id eq 21 and centre/id eq 25



Item Response Resource

Candidates responses are returned as part of the HistoricalResult response in raw XML format ("candidateResponse" property) or via a user friendly model accessible via a separate resource. Further information regarding the Item Response resource can be found by selecting the following link:

Item Response Resource



Required Permissions

To successfully call the HistoricalResult methods, the user specified in the header of the request must have the 'View Reporting' permission in Surpass and be associated to the relevant centre and subject contained within the request.

Feedback and Knowledge Base