CustomReportGeneration API
In Surpass, the Custom Reports (beta) screen is where proficient HTML writers can create custom reports for individual candidates based on test result data.
Custom reports can be generated from custom report templates in the Custom Reports (beta) screen or by using the CustomReportGeneration API. For more information, read About Custom Reports (beta).
The CustomReportGeneration API resource is used to generate custom reports. The CustomReport API lets you list, retrieve, and delete custom report templates.
This article explains what calls can be made to the Surpass API using the CustomReportGeneration resource.
Import this API into your Postman Workspace
In This Article
Generating a custom report
Send a request to the endpoint to generate a custom report. The custom report template’s unique identifiers and any candidates’ keycodes are required in the request body.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
Sample request
The following request contains the minimum required request body to generate a custom report.
{
"id": 1,
"parameters": [
{
"entity": "TestResult",
"values": [
"MCW6PT7K"
]
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
id integer mandatory
The custom report template’s unique identifier.
reference string optional
The custom report template’s unique reference code.
parameters array mandatory
Contains the custom report parameters’ information.
parameters/entity enumeration
The custom report’s entity. For more information on what each entity contains, read ‘Custom report entities’ below.
TestResult is currently the only available entity.
parameters/values array
Contains the candidates’ unique keycode(s). These keycodes must be for finished test sessions.
customData array optional
Contains any information not included in the specified parameters/entity property that you want to include in the report.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the custom report’s details.
{
"id": 1,
"report": {
"id": "3f0cb6-757d34ca-d48e-420c-9533-eee41d9cb6b4",
"url": "https://{your Surpass instance}.surpass.com/api/v2/CustomReportGeneration/3f0cb6-757d34ca-d48e-420c-9533-eee41d9cb6b4"
},
"reference": "mike",
"templatingEngine": "Scriban",
"href": "https://{your Surpass instance}.surpass.com/api/v2/CustomReport/1",
"errors": null
}
This sample report is based on the sample custom report template found in the ‘View sample response’ section of CustomReport API
Response body schema
The response body schema contains a description of every property that is returned by this endpoint.
id integer
The custom report template’s unique identifier.
report object
Contains the custom report’s informaton.
report/id string
The custom report’s unique identifier.
report/url string
The endpoint used to generate the custom report, such as /api/v2/CustomReportGeneration/{id} where {id} is the custom report’s unique identifier.
reference string
The custom report template’s unique reference code.
templatingEngine enumeration
The templating engine used for the custom report and its template. Currently, the only available engine is Scriban.
href string
The endpoint to call the custom report template’s information, such as /api/v2/CustomReport/{id} where {id} is the custom report template’s unique identifier.
errors string
Information about any errors that occurred during the request.
Custom report entities
Custom report entities are the database objects that can be used to display information in a custom report. Properties from these entities should be included in the custom report template’s HTML in the form of Scriban templating text. These Scriban placeholders correspond to the entity properties to indicate what information should be retrieved for the keycode(s). Read the Scriban readme for more information on how to use Scriban.
TestResult
The TestResult entity contains test result information.
Sample TestResult entity
The following sample contains all of the properties available in the TestResult entity, in JSON format.
{
"KeyCode": "MCW6PT7K",
"Centre": {
"Id": 1,
"Reference": "Centre1",
"Name": "Surpass Centre"
},
"Subject": {
"Id": 1,
"ItemBankSubjectId": 0,
"Name": "Geography Subject",
"Reference": "Subject1",
"ExternalReference": null,
"Status": 1,
"CreateDate": "0001-01-01T00:00:00",
"UpdateDate": "0001-01-01T00:00:00",
"OwnerNames": null,
"ItemsCount": 0,
"IsChildSubject": null,
"Type": 0,
"HasSubjectGroups": false,
"DeliveryType": 0,
"SupportedContentType": 0,
"SubjectCentres": [],
"DirectlyAssignedCentres": [],
"DirectlyAssignedSubjectCentres": [],
"FontFamily": 0,
"FontSize": 0,
"IsSecureDocuments": false,
"CustomCssId": null,
"IsGlobalShared": false,
"Centres": [],
"SharedCentres": [],
"SubjectProgrammeTagId": null,
"SubjectProgrammeTag": null,
"CheckBoxItemMode": 0
},
"Candidate": {
"Id": 1,
"Reference": "Candidate1",
"Name": {
"Forename": "Sanjib",
"Middlename": "",
"Surname": "Datta"
},
"DateOfBirth": "1981-07-15T00:00:00",
"Gender": "U",
"Email": ""
},
"Completion": "2022-01-20T00:01:00",
"StartDate": "2022-01-20T09:34:53.747",
"Grade": null,
"AdjustedGrade": "Pass",
"Pass": true,
"TimeTaken": "00:05:35.0130000",
"Duration": "00:10:00",
"UserMarks": 0.0,
"TotalMarks": 2.0,
"PassMark": 0.0,
"Test": {
"Id": 1,
"Reference": "Test1",
"Name": "Geography Test"
},
"TestForm": {
"Id": 1,
"Name": "Geography Final Year Test Form 2022",
"Reference": "TestForm1",
"SubjectId": 0,
"TestId": 0,
"Status": 0,
"Valid": null
},
"LearningOutcomes": [],
"ScoreBoundaryItems": [],
"Sections": [
{
"Id": 1,
"Name": "Section 1",
"Items": [
{
"Mark": 1.0,
"ActualMark": 1.0,
"TimeTaken": "00:02:00.00",
"Attempted": true,
"ItemPresentationOrder": 1,
"Question": {
"Name": "MCQ 1",
"TotalMark": 1.0,
"ItemId": "5420P1",
"Version": 2,
"Metadatas": [
{
"Name": "CSO",
"Value": "0"
},
{
"Name": "displayName",
"Value": ""
},
{
"Name": "displayNumber",
"Value": "1"
},
{
"Name": "flagged",
"Value": "0"
},
{
"Name": "ItemType",
"Value": "Unspecified"
},
{
"Name": "Keywords",
"Value": ""
},
{
"Name": "LO",
"Value": ""
},
{
"Name": "markingState",
"Value": "0"
},
{
"Name": "MarkingType",
"Value": "0"
},
{
"Name": "mediaPlays",
"Value": "0"
},
{
"Name": "quT",
"Value": "10"
},
{
"Name": "TotalMark",
"Value": "1"
},
{
"Name": "type",
"Value": "1"
},
{
"Name": "unit",
"Value": ""
},
{
"Name": "userCompleted",
"Value": "0"
},
{
"Name": "UsesMp4",
"Value": "0"
}
]
},
"AlgorithmResponse": null
},
{
"Mark": 1.0,
"ActualMark": 0.0,
"TimeTaken": "00:06:00",
"Attempted": false,
"ItemPresentationOrder": 2,
"Question": {
"Name": "MCQ 2",
"TotalMark": 0.0,
"ItemId": "5420P2",
"Version": 2,
"Metadatas": [
{
"Name": "CSO",
"Value": "0"
},
{
"Name": "displayName",
"Value": ""
},
{
"Name": "displayNumber",
"Value": "2"
},
{
"Name": "flagged",
"Value": "0"
},
{
"Name": "ItemType",
"Value": "Unspecified"
},
{
"Name": "Keywords",
"Value": ""
},
{
"Name": "LO",
"Value": ""
},
{
"Name": "markingState",
"Value": "0"
},
{
"Name": "MarkingType",
"Value": "0"
},
{
"Name": "quT",
"Value": "10"
},
{
"Name": "TotalMark",
"Value": "1"
},
{
"Name": "type",
"Value": "1"
},
{
"Name": "unit",
"Value": ""
},
{
"Name": "userCompleted",
"Value": "0"
},
{
"Name": "UsesMp4",
"Value": "0"
}
]
},
"AlgorithmResponse": null
},
{
"Mark": 1.0,
"ActualMark": 1.0,
"TimeTaken": "00:02:00.00",
"Attempted": true,
"ItemPresentationOrder": 3,
"Question": {
"Name": "MCQ 3",
"TotalMark": 1.0,
"ItemId": "5420P93",
"Version": 7,
"Metadatas": [
{
"Name": "CSO",
"Value": "0"
},
{
"Name": "displayName",
"Value": ""
},
{
"Name": "displayNumber",
"Value": "1d"
},
{
"Name": "flagged",
"Value": "0"
},
{
"Name": "ItemType",
"Value": "Unspecified"
},
{
"Name": "Keywords",
"Value": ""
},
{
"Name": "LO",
"Value": ""
},
{
"Name": "markingState",
"Value": "0"
},
{
"Name": "MarkingType",
"Value": "0"
},
{
"Name": "mediaPlays",
"Value": "0"
},
{
"Name": "quT",
"Value": "10"
},
{
"Name": "surpassGroupID",
"Value": "1"
},
{
"Name": "surpassGroupName",
"Value": "Group 1"
},
{
"Name": "TotalMark",
"Value": "1"
},
{
"Name": "type",
"Value": "1"
},
{
"Name": "unit",
"Value": ""
},
{
"Name": "userCompleted",
"Value": "0"
},
{
"Name": "UsesMp4",
"Value": "1"
}
]
},
"AlgorithmResponse": null
}
],
"AverageTimeTaken": "00:00:09.0040000"
}
]
}TestResult entity schema
The schema contains a description of every property that can be found in the TestResult entity.
KeyCode string
The candidate’s unique keycode, used to enter their test.
Centre object
Contains the centre’s information.
Centre/Id integer
The centre’s unique identifier.
Centre/Reference string
The centre’s unique reference code.
Centre/Name string
The centre’s name.
Subject object
Contains the subject’s information.
Subject/Id integer
The subject’s unique identifier.
Subject/ItemBankSubjectId integer
Subject/Name string
The subject’s name.
Subject/Reference string
The subject’s unique reference code.
Subject/ExternalReference string
Any external reference associated with the subject.
Subject/Status enumeration
Determines the subject’s status. 0 indicates the subject is active.
Subject/CreateDate string
The date the subject was created, in YYYY/MM/SSTHH:MM:SS format.
Subject/UpdateDate string
The date the subject was last updated, in YYYY/MM/SSTHH:MM:SS format.
Subject/OwnerNames array
The names of any subject owners.
Subject/ItemsCount integer
The number of items in the subject.
Subject/IsChildSubject Boolean
Subject/Type enumeration
Subject/HasSubjectGroups Boolean
Determines whether the subject is any subject groups.
Subject/DeliveryType enumeration
Determines whether the subject’s delivery type is OnScreen (0) or OnPaper (1).
Subject/SupportedContentType enumeration
Determines whether the subject’s content type is Mixed (0) or HTML (1).
Subject/SubjectCentres array
Contains any centres the subject is in.
Subject/DirectlyAssignedCentres array
Contains the primary centre assigned to the subject upon creation.
Subject/DirectlyAssignedSubjectCentres array
Contains any other centres shared with the subject.
Subject/FontFamily enumeration
Determines the subject’s default font family.
Subject/FontSize enumeration
Determines the subject’s font size.
Subject/IsSecureDocuments Boolean
Subject/CustomCssId integer
The unique identifier of any custom CSS file associated with the subject.
Subject/isGlobalShared Boolean
Determines whether the subject is shared with all centres (true) or not (False).
Subject/Centres array
Contains any centres the subject is in.
Subject/SharedCentres array
Contains any other centres shared with the subject.
Subject/SubjectProgrammeTagId integer
Contains the subject tag’s unique identifier.
Subject/SubjectProgrammeTag string
Contains the subject tag’s name.
Subject/CheckBoxItemMode enumeration
Determines whether checkboxes are enabled in delivery for Multiple Choice, Multiple Response, and Either/Or items, and Multiple Choice and Multiple Response survey items.
Candidate object
Contains the candidate’s information.
Candidate/Id integer
The candidate’s unique identifier.
Candidate/Reference string
The candidate’s unique reference code.
Candidate/Name object
Contains the information for the candidate’s name.
Candidate/Name/Forename string
The candidate’s first name.
Candidate/Name/Middlename string
The candidate’s middle name.
Candidate/Name/Surname string
The candidate’s last name.
Candidate/DateOfBirth string
The candidate’s date of birth in YYYY/MM/SSTHH:MM:SS format.
Candidate/Gender enumeration
The candidate’s gender, if specified.
Candidate/Email string
The candidate’s email address.
Completion string
The date the test was finished, in YYYY/MM/SSTHH:MM:SS format.
StartDate string
The date the test was started, in YYYY/MM/SSTHH:MM:SS format
Grade string
The grade achieved by the candidate.
AdjustedGrade string
The adjusted grade achieved by the candidate.
Pass Boolean
Determines whether the candidate passed the test (true) or not (False).
TimeTaken string
The time taken by the candidate to complete the test, in HH:MM:SS format.
Duration string
The total test duration, in HH:MM:SS format.
UserMarks integer
The marks achieved by the candidate.
TotalMarks integer
The total marks available for the test.
PassMark integer
The mark required to pass the test.
Test object
Contains the test’s information.
Test/Id integer
The test’s unique identifier.
Test/Reference string
The test’s unique reference code.
Test/Name string
The test’s name.
TestForm object
Contains the test form’s information.
TestForm/Id integer
The test form’s unique identifier.
TestForm/Name string
The test form’s name.
TestForm/Reference string
The test form’s unique reference code.
TestForm/SubjectId integer
The unique identifier of the test form’s subject.
TestForm/TestId integer
The unique identifier of the test form’s test.
TestForm/Status enumeration
Determines the test form’s workflow status. 0 indicates the test is active.
TestForm/Valid Boolean
Determines whether the test form is valid (true) or not (False).
LearningOutcomes array
Contains any learning outcomes’ information.
ScoreBoundaryItems array
Contains any score boundaries’ information.
Sections array
Contains the test form’s section information, including the test session’s result data.
Sections/Id integer
The section’s unique identifier.
Sections/Name string
The section’s name.
Sections/Items array
Contains the item(s) in the section’s information.
Sections/Items/Mark integer
The mark available for the item.
Sections/Items/ActualMark integer
The mark achieved by the candidate.
Sections/Items/TimeTaken string
The time taken by the candidate to answer the question, in HH:MM:SS format.
Sections/Items/Attempted Boolean
Determines whether the candidate attempted the question (true) or not (False).
Sections/Items/ItemPresentationOrder integer
The position of the item in the test.
Sections/Items/Question object
Contains the question’s information.
Sections/Items/Question/Name string
The question’s name.
Sections/Items/Question/TotalMark integer
The total mark available for the question.
Sections/Items/Question/ItemId integer
The question’s unique identifier.
Sections/Items/Question/Version integer
The question’s version.
Sections/Items/Question/Metadatas array
Contains the information for any metadata associated with the question, such as displayName, displayNumber, and flagged, or any assigned tags.
Sections/Items/Question/Metadatas/Name string
The metadata’s name.
Sections/Items/Question/Metadatas/Value string
The metadata’s value.
Sections/Items/AlgorithmResponse string
The response after any associated algorithm has been applied.
Sections/AverageTimeTaken string
The average time taken by the candidate to finish a section, in HH:MM:SS format.
Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Name |
Code |
Description |
|---|---|---|
|
InternalServer |
1 |
Internal server error. |
|
Unauthorized |
3 |
The request has been sent by an unauthorised user. |
|
IncorrectFieldFormat |
4 |
A field in the request has not been completed in the correct format. |
|
InaccessibleOperation |
5 |
The request has been sent by a user with invalid permissions. |
|
InaccessibleData |
6 |
The request has been sent by a user with invalid permissions. |
|
MissingBody |
7 |
There is an issue with the request body. |
|
CustomReportGenerationError |
209 |
There is an issue with generating the custom report. |
|
CustomReportDoesNotExist |
213 |
The custom report specified in the request does not exist. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: