RescoringRule Resource

Within reporting Surpass provides the functionality to re-score items within given time periods after statistical analysis has been completed by an organisation. It might be that a question does not reflect the difficulty of a test or that it has been delivered to the candidate incorrectly, in either case Surpass offers the ability for a user to re-score these tests based on completed analysis. The system allows users to change answer options, change an item to give candidates full marks and remove items from the total score of a test. This all can drastically affect candidates results.

These results are retrievable from the Surpass API via the analytics result and historical result resources. These resources provide the information that relates to that result, it does not inform the user of all of the rules that were applied to get this result. However a resource on the Surpass API 'RescoringRules' allows users to retrieve this information from the historical/analytics result resource via a href included within its response. The information returned from this resource maps to the changes that were made in the re-scoring event user interface in reporting since the test was delivered. All changes will be returned here regardless of the amount of times a test has been re-scored, this is so a consumer can identify the exact changes that made a result the way it is including user audit information.

In the below image the information returned in this resource maps to the changes done in this rescoring event, these are highlighted in the "Changed" column for items delivered and the "Scoring Data" column in the test form.


RescoringRule Resource

Below we have listed the operations, HTTP verbs and an example URL for the RescoringRule resource within the Surpass API. 

Operation HTTP Verb Example URL
Search and Filter GET https://...surpass.com/api/v2/RescoringRule/
https://...surpass.com/api/v2/RescoringRule?$filter=subject/reference eq 'BTLTest'
Read (individual) GET https://...surpass.com/api/v2/RescoringRule/1

Attributes for the RescoringRule Resource

Within the table below we have provided all of the attributes included in the RescoringRule resource. This includes the attribute name, data type, if the attribute is orderable when requesting the GET method and if the attribute is available to filter when requesting the GET method.

Property Name Type Description Filter
(GET)
Available
Operators
(GET)
rescoredItems collection A collection of items that have been rescored as part of this rule
rescoredItems / rescoredItem object an Item that has been rescored
rescoredItems / rescoredItem / answerOptions collection This collection is only displayed for multiple choice, multiple response and either / or question types.
rescoredItems / rescoredItem / answerOptions / label string The answer option label
rescoredItems / rescoredItem / answerOptions / displayLabel string The answer option label displayed in delivery
rescoredItems / rescoredItem / answerOptions / contentType enumeration The content type for the answer option.
Available values: "RichText", "Image", "MathML"
rescoredItems / rescoredItem / answerOptions / originalMark int The mark assigned to an answer option at delivery
rescoredItems / rescoredItem / answerOptions / newMark int The new mark assigned to an answer option after the rescoring event
rescoredItems / rescoredItem / itemId string The Item ID that was rescored
rescoredItems / rescoredItem / itemVersion int The version of the item that was rescored
rescoredItems / rescoredItem / type enumeration The question type of the item that was rescored
rescoredItems / rescoredItem / questionText string The question text used for the item that was rescored
rescoredItems / rescoredItem / totalMark int The total mark for the item that was rescored
rescoredItems / rescoredItem / contentType enumeration The content type for the question
rescoredItems / rescoredItem / unattempted int The mark assigned if the question was unattempted.
rescoredItems / changeAction enumeration The type of change made in the rescoring event.
Available values: "FullMarkedUnattempted", "Deleted", "ChangeAnswer"
user resource
(object)
The user that completed the rescoring event x eq
subject resource
(object)
The subject of the test that the rescoring event applies to x eq
test resource
(object)
The test that the rescoring event applies to x eq
testForm resource
(object)
The test form that the rescoring event applies to. x eq
startDate dateTime The start date of the rescoring event
endDate dateTime The end date of the rescoring event
savedDate dateTime The date that the rescoring event was saved and applied. x le, ge
historicalResults resource
(collection)
A list of historical results that are affected by the rescoring event. This will only return the latest affected historical results rather than all that have been affected ever.
scoringData collection A collection of changes made to the test level settings
scoringData / testFormVersion int The test form version the change relates to
scoringData / scaleScoreMapping resource
(object)
A URL to the full mapping of the scale score in the rescoring event
scoringData / gradeBoundaries collection A collection of the grade boundaries applied for the rescoring event
scoringData / gradeBoundaries / minRawScore int The raw score the candidate would need to achieve to get the grade
scoringData / gradeBoundaries / grade string The grade the candidate would receive
scoringData / loBoundaries collection The learning outcome boundaries that have been applied in the rescoring event
scoringData / loBoundaries / learningOutcomeBoundariesApplied boolean The check box to inform if the rescoring event has been updated to have its learning outcome boundaries applied.
scoringData / loBoundaries / learningOutcomeBoundaries collection The learning outcome boundaries that have been applied in the rescoring event. These learning outcome boundaries must meet the threshold value to be listed. 
scoringData / loBoundaries / learningOutcomeBoundaries / isDefault   boolean This flag identifies if the learning outcome boundary has had the default pass mark assigned to it, if false this is a user defined value. 
scoringData / loBoundaries / learningOutcomeBoundaries / text   string This flag identifies the learning outcome boundary value 
scoringData / loBoundaries / learningOutcomeBoundaries / passPercentage   int This value identifies the pass percentage the candidate requires to pass this learning outcome boundary, and therefore the test.

Additional Notes

  • Depending on the question types will depend on the response that is presented in the rescoredItems Collection. The above table shows all rescoring actions but some properties will be omitted if they are not relevant to that action.


GET Request and Return 

The GET RescoringRules 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 RescoringRule 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 Using the Surpass API.

Example GET request & response (JSON)

Example GET request & response (XML)


Filtering RescoringRule on Resource objects

The GET RescoringRule method allows you to filter on resource objects contained within the RescoringRule Resource. The Surpass API allows users to filter on resources subject, user, test and test form where rescoring rules have been applied. When filtering on these resources, 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 RescoringRule Resource. Below we have provided some examples of how these requests are built:

https://...surpass.com/api/v2/RescoringRule?$filter=subject/reference eq 'BTLTest'

https://...surpass.com/api/v2/RescoringRule?$filter=subject/id eq '20'  


Required Permissions

To successfully call the RescoringRule methods, the user specified in the header of the request must have the 'Rescore Candidate Script' permission in Surpass and be associated to the relevant centre and subject that is contained within the request. 

 

Feedback and Knowledge Base