Report Resource

Within Surpass we are continually improving the reports and statistics that can be extracted from Surpass. All of the item performance, test performance and centre statistics are captured in the Surpass system and the Report resource offers a mechanism to extract this data in XML format.

The report resource works by finding out the report details through sending an individual GET request and then using the report parameters provided to construct a URL which generates the report.

Report Resource

Below we have listed the operations, http verbs and an example URL for the report resource within the Surpass API.
Operation HTTP Verb Example URL
List GET https://...surpass.com/api/v2/Report/
Read (Individual) GET https://...surpass.com/api/v2/Report/{id}
Attributes for the Report Resource

Within the table below we have provided all of the attributes included in the report 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.
Attribute Name Type Description Order (GET) Filter (GET) Available Operators (GET)
id int
reference String
href String
name String
reportParameters object The report parameters are passed into the GET URL to generate a report. Please see the Report Generation section to find out more information on this.

GET Request and Return

The Report resource can be called directly by browsing to the URL, any required parameters such as $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)


Report Parameters

Once the report parameters are known they would form part of the URL to generate a report. COLLECTION, DATETIME and STRING are returned as part of the report parameters, below we have explained how each is constructed.
  • All required subjects, centres, tests, test forms, folders and items in the parameter collection require the relevant Surpass reference or ID.
  • COLLECTION – This allows for multiple values to be contained in an array. To specify multiple values the collection must be used in the following format: {"Sample 1", "Sample 2", "Sample 3"}
  • DATETIME – The DATETIME values can be any that could be parsed by C#. The DATETIME value also must be kept inside double quotes. An example DATETIME is as follows: 2013-12-18T07:23:26.550375+00:00
  • STRING – Single value that must be contained within double quotes.
  • When defining the status for the distractor analysis report you must provide the ID. Draft = 0, Ready for Review = 1, Reviewed = 2, Live = 3, Withdrawn = 4.

Required Permissions

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

Report Generation

After all of the report details and parameters have been gathered from the resource the report parameters can be used to generate a report within Surpass. Below we have outlined the full process on how to achieve this:
  1. Send a request to the resource to find all available reports. This will return the ID, reference and href. Use this information to find out the parameters for each report by sending an individual GET request.
    http://...surpass.com/api/v2/Report/

  2. Send an individual GET request specifying the ID of the report. This will provide you with the necessary information to generate a report.
    http://...surpass.com/api/v2/Report/1

  3. Once the report parameters are known, they would form part of the URL sent in the request. An example of this is as follows:
    https://...surpass.com/api/v2/Report/1?generate=true&startDateRange=2013-01-20T00:00:00&endDateRange=2013-02-20T00:00:00¢res={“BTLTest}&subjects={“Demo-SF”}& TestFormReference=“Demo Form - SF”

  4. Optional report parameters can be omitted from the URL. If a report doesn’t require any parameters it can be stated as follows:
    https://...surpass.com/api/v2/Report/1?generate=true

NOTE – Please be aware that generating reports that may return large amounts of data may take a while to respond and it is highly recommended to utilise the report parameters as much as possible to search for exactly what is required.

All report information is provided in XML and contained within the data attribute of the response. An example has been provided here.


Available Reports

Below we have provided a link which lists all of the available reports, which parameters are mandatory, where a collection of references can be specified and what the parameters default to if it is omitted from the URL.

Attributes and Parameters for the Reports

Feedback and Knowledge Base