AnalyticsResult Resource
Within the Surpass API there a several different types 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 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.
AnalyticsResult Resource
Below we have listed the operations, http verbs and an example URL for the AnalyticsResult resource within the Surpass API.
| Operation | HTTP Verb | Example URL |
|---|---|---|
| Search and Filter | GET | https://...surpass.com/api/v2/AnalyticsResult/ |
| Read (individual) | GET | https://...surpass.com/api/v2/AnalyticsResult/1 https://...surpass.com/api/v2/AnalyticsResult/A1B2C3D4 |
Properties for the AnalyticsResult Resource
In the table below we have provided all of the properties included in the AnalyticsResult Resource. This includes: the property name, type, if the attribute is available to filter when requesting the GET method and the available operators..
| Property Name | Type | Description | Filter (GET) |
Available Operators (GET) |
|---|---|---|---|---|
| historicalResults | resource (collection) |
A collection of the previous states of the result due to affects from rescoring | ||
| historicalResults / id | int | The unique id of the previous state of the analytics result | ||
| historicalResults / href | string | The request URL to retrieve the historical result | ||
| changeDetails | object | an object containing details of any changes to the analytics result | ||
| changeDetails / type | enumeration | The latest change to affect the analytics 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 analytics result | ||
| changeDetails / user / id | int | The id of the user that applied the change to the analytics 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 analytics result | ||
| changeDetails / rescoringRules | resource (object) |
Information on the exact rescoring rules that have been applied to the analytics 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 analytics result. | ||
| id | int | The unique id for this result. | ||
| reference | string | The reference for this resource is the keycode assigned to the test session which is used by the candidate to start the test. | ||
| 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. | ||
| scaleScore | int | The scale score the candidate received for this result. | ||
| 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. | ||
| 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 / isSurveySection | boolean | This indicates whether the section is set up as a survey section which contains non-scored question items for candidates to record their opinions (such as their feedback on the test experience). | ||
| 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 analytics 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/AnalyticsResult?$filter=warehousedDate ge 08/06/2015T00:00:00 and warehousedDate le 09/06/2015T00:00:00
· The AnalyticsResult resource has been extended to provide a user friendly item response model for MCQ, MRQ and Either or question types. This can be requested by calling the Item Response Resource directly or within the AnalyticsResult response by passing the query string parameter 'showItemResponses=true' to the GET/{id}, GET{Keycode} method. Below we have provided the request URL for the methods of extracting item responses:
https://...surpass.com/api/v2/AnalyticsResult/{Keycode/ID}?showItemResponses=true - returns full analyticsResult request with the item response model
https://...surpass.comapi/v2/AnalyticsResult/{Keycode/ID}/ItemResponse/{Item Authoring ID} - returns the response for one item
https://...surpass.comapi/v2/AnalyticsResult/{Keycode/ID}/ItemResponse/ - returns a list of the item response URLs contained within a analytcisResult
GET AnalyticsResult Request and Return
The AnalyticsResult 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 Result 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 AnalyticsResults on Resource objects
The GET AnalyticsResult method allows you to filter on resource objects contained within the AnalyticResult 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/AnalyticsResult?$filter=subject/reference eq 'subject ref 1' and centre/reference eq 'centre ref 1’
https://...surpass.com/api/v2/AnalyticsResult?$filter=subject/id eq 21 and centre/id eq 25
Item Response Resource
Candidates responses are returned as part of the AnalyticsResult 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:
Required Permissions
To successfully call the AnalyticsResult methods, the user specified in the header of the request must have the 'View Reporting' and 'View Results' permission in Surpass and be associated to the relevant centre and subject contained within the request.