TestScript OAPI

The TestScript OAPI lets you retrieve test script information for a specified keycode, from the Script Review screen, optionally including complete marking history information.

This article explains what calls can be made to the SecureMarker OAPI using the TestScript resource.

Import this API into your Postman Workspace

Retrieving test scripts

get /SecureMarker/api/TestScript/{keycode}

Send a request to the endpoint to retrieve information for a specific test script using its keycode. No request body is required.

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.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.
keycode	path MANDATORY	`/api/testscript/{keycode}`	Returns information for the specified test script, where `{id}` is the test script’s keycode.
includeMarkingHistory	query OPTIONAL	`/api/testscript/{keycode}?includeMarkingHistory={Boolean}`	Determines whether to include marking history information in the response, where `{keycode}` is the test script’s keycode and `{Boolean}`is one of `true` or `false`.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.

{
  "ID": 1,
  "Keycode": "TND7XDXX",
  "TestForm": {
    "Name": "Final Year Geography Test Form January 2022",
    "Reference": "TestForm1",
    "Id": 1
  },
  "Test": {
    "Name": "Final Year Geography Test",
    "Reference": "Test1",
    "Id": 1
  },
  "Subject": {
    "Name": "Geography Subject",
    "Reference": "Subject1",
    "Id": 1
  },
  "AssignmentGroup": null,
  "Flagged": false,
  "Vip": false,
  "Moderated": false,
  "State": "Marking In Progress",
  "Sections": [
    {
      "Name": "A",
      "Items": [
        {
          "ID": "1",
          "Name": "Item 1",
          "DoubleMarking": 0,
          "CI": false,
          "TotalMark": 5,
          "MarkingGroupID": 1,
          "ViewingGroups": null,
          "Mark": 3,
          "LearningOutcomes": null,
          "AssignedMarks": null
        },
        {
          "ID": "2",
          "Name": "Item 2",
          "DoubleMarking": 0,
          "CI": false,
          "TotalMark": 5,
          "MarkingGroupID": 1,
          "ViewingGroups": null,
          "Mark": 2,
          "LearningOutcomes": null,
          "AssignedMarks": null
        },
        {
          "ID": "3",
          "Name": "Item 3",
          "DoubleMarking": 0,
          "CI": false,
          "TotalMark": 5,
          "MarkingGroupID": 1,
          "ViewingGroups": null,
          "Mark": 4,
          "LearningOutcomes": null,
          "AssignedMarks": null
        }
      ]
    },
    {
      "Name": "B",
      "Items": [
        {
          "ID": "4",
          "Name": "Item 4",
          "DoubleMarking": 0,
          "CI": false,
          "TotalMark": 5,
          "MarkingGroupID": 2,
          "ViewingGroups": null,
          "Mark": 3,
          "LearningOutcomes": [
            {
              "Name": "Tag Group 1",
              "Mark": 2,
              "MaxMark": 3
            },
            {
              "Name": "Tag Group 2",
              "Mark": 2,
              "MaxMark": 2
            }
          ],
          "AssignedMarks": null
        },
        {
          "ID": "5",
          "Name": "Item 5",
          "DoubleMarking": 0,
          "CI": false,
          "TotalMark": 7,
          "MarkingGroupID": 2,
          "ViewingGroups": null,
          "Mark": 5,
          "LearningOutcomes": [
            {
              "Name": "Tag Group 1",
              "Mark": 2,
              "MaxMark": 3
            },
            {
              "Name": "Tag Group 2",
              "Mark": 1,
              "MaxMark": 2
            },
            {
              "Name": "Tag Group 3",
              "Mark": 2,
              "MaxMark": 2
            }
          ],
          "AssignedMarks": null
        }
      ]
    }
  ]
}

EXAMPLE: In this sample response, test script details are retrieved for keycode TND7XDXX.

Response schema

The response schema contains a description of every property that can be returned for this endpoint.

ID integer

The test script’s unique identifier.

Keycode string

The test script’s unique keycode.

TestForm object

Contains the test form’s information for the specified test script.

TestForm/Name string

The test form’s name.

TestForm/Reference string

The test form’s unique reference code.

TestForm/ID integer

The test form’s unique identifier.

Test object

Contains the test’s information for the specified test script.

Test/Name string

The test’s name.

Test/Reference string

The test’s unique reference code.

Test/ID integer

The test’s unique identifier.

Subject object

Contains the subject’s information for the specified test script.

Subject/Name string

The subject’s name.

Subject/Reference string

The subject’s unique reference code.

Subject/ID integer

The subject’s unique identifier.

AssignmentGroup string

The name of the test script’s assignment group. If the test script is not part of an assignment group, returns null.

Flagged Boolean

Determines whether test script has been flagged in the Script Review screen (true), or not (false).

Vip Boolean

Determines whether VIP Mode has been enabled for the test script in the Script Review screen (true), or not (false).

Moderated Boolean

Determines whether the test script has been moderated (true), or not (false).

State enumeration

The current status of the test script, which can be one of:

Marking Not Yet Started – Marking has not started for the script.
Marking In Progress – Marking is in progress for the script.
Marking Complete – Marking is complete for the script.
Result Pending – The script can be confirmed from SecureMarker to Surpass. For more information, read Sending completed scripts from SecureMarker to Surpass.
Result Confirmed and Archived – The script’s result is confirmed and has been automatically exported to Surpass.
Fail To Export – The script has failed to export to Surpass.

Sections array

Contains the test form’s sections’ information.

NOTE: If the test form contains multiple sections, a separate object is returned for each section.

Sections/Name string

The section’s name.

Sections/Items array

Contains the information for the items in the section.

NOTE: If the section contains multiple items, a separate object is returned for each item.

Sections/Items/ID integer

The item’s unique identifier.

Sections/Items/Name string

The item’s name.

Sections/Items/DoubleMarking enumeration

Determines whether the item’s Marking Type is set to Single Marking (0), Double Marking (1), or Blind Double Marking (2).

Sections/Items/CI Boolean

Determines whether the item is a control item (true), or not (false).

Sections/Items/TotalMark integer

The item’s total available mark.

Sections/Items/MarkingGroupID integer

The unique identifier of the item’s item group. If the item is not part of an item group, returns null.

Sections/Items/ViewingGroups array

Contains information for any item groups the item is a part of in a view-only capacity. If the item is not part of any such item group, returns null.

Sections/Items/ViewingGroups/GroupID integer

The item group’s unique identifier.

Sections/Items/Mark integer

The mark achieved by the candidate for the item.

Sections/Items/LearningOutcomes array

Contains information for any Marked Learning Outcomes.

NOTE: If the item contains multiple Marked Learning Outcomes, a separate object is returned for each Marked Learning Outcome.

Sections/Items/LearningOutcomes/Name string

The Marked Learning Outcome’s name.

Sections/Items/LearningOutcomes/Mark integer

The mark assigned for the Marked Learning Outcome.

Sections/Items/LearningOutcomes/MaxMark integer

The total available mark for the Marked Learning Outcome.

Sections/Items/AssignedMarks array

Contains information about any assigned marks and by whom they were assigned – the full marking history. If the includeMarkingHistory query parameter is not included in the request (or set to false), returns null.

NOTE: If the item contains multiple marks, a separate object is returned for each mark.

Sections/Items/AssignedMarks/UserID integer

The marker’s unique (user) identifier.

Sections/Items/AssignedMarks/Username string

The marker’s username.

Sections/Items/AssignedMarks/Forename string

The marker’s first name.

Sections/Items/AssignedMarks/Surname string

The marker’s surname.

Sections/Items/AssignedMarks/Timestamp string

The date and time the mark was assigned, in in YYYY-MM-DDTHH:SS format.

Sections/Items/AssignedMarks/MarkingType enumeration

The type of mark applied, which can be one of:

Adjudication – mark assigned during adjudication. Read Adjudicating responses in SecureMarker for more information.
Auto-mark – response has been computer-marked.
Automatic aggregation – mark aggregated from two blind markers. Read Setting up double marking and ‘Marking double marked responses’ in Marking responses in SecureMarker for more information.
CI Approval – control item approved. Read Reviewing control items in SecureMarker for more information.
CI Creation – control item created. Read Creating control items in SecureMarker for more information.
CI Review Disagree – control item disapproved. Read Reviewing control items in SecureMarker for more information.
CI Review Discard – control item discarded during review. Read Reviewing control items in SecureMarker for more information.
De-escalate – the mark assigned upon de-escalation. Read Reviewing escalated responses in SecureMarker for more information.
Discard – control item discarded. Read Discarding control items in SecureMarker for more information.
Double Marking – the mark assigned by the second of two blind markers. Read Setting up double marking and ‘Marking double marked responses’ in Marking responses in SecureMarker for more information.
Escalate – mark assigned upon escalation. Read Escalating a response in the Marking screen of SecureMarker for more information.
Escalation marking – mark assigned during escalation review. Read Reviewing escalated responses in SecureMarker for more information.
Escalation remark – another mark assigned during escalation review. Read Reviewing escalated responses in SecureMarker for more information.
Live mark discard – assigned mark was discarded. A mark of 0 is returned, but the response is returned to the marking pool. Read ‘Discarding marks’ in Reviewing marked responses in the Quotas screen for more information.
Moderation – mark assigned upon moderation. Read Moderating a script in SecureMarker for more information.
Normal Marking – the first mark given to the response. Read Marking responses in SecureMarker for more information.

NOTE: Where an automatic marking process has occurred, marker details are also returned with anonymous values.

Sections/Items/AssignedMarks/Mark integer

The mark assigned.

Sections/Items/AssignedMarks/ZeroMarkedCode string

The zero marked code assigned. If no zero marked code is assigned, returns null.

Sections/Items/AssignedMarks/Escalation object

If Sections/Items/AssignedMarks/MarkingType is set to Escalate, contains escalation information.

Sections/Items/AssignedMarks/Escalation/Issues array

Contains the issue(s) specified by the escalator. For more information, read ‘Assigning marks to an escalated response‘ in Reviewing an escalated response in the Escalations screen.

NOTE: If multiple issues have been specified, a separate object is returned for each issue.

Sections/Items/AssignedMarks/Escalation/Issues/Value enumeration

The specified issue.

Sections/Items/AssignedMarks/Escalation/Comment string

Any comments left by the escalator. If no comment was left, returns null.

Sections/Items/AssignedMarks/GeneralComment string

Any comments left by the marker. If no comment was left, returns null.

Sections/Items/AssignedMarks/ModerationComment string

Any comments left by the moderator. If no comment was left, returns null.

Sections/Items/AssignedMarks/IsConfirmedMark enumeration

Determines whether mark is the confirmed, final mark (1) or not (0).

Sections/Items/AssignedMarks/DiscardedMark string

If the Sections/Items/AssignedMarks/MarkingType is set to Live mark discard, details the marker’s forename, surname, and a timestamp for the discard in in YYYY-MM-DDTHH:SS format.

Sections/Items/AssignedMarks/LearningOutcomes array

Contains information about any marks assigned to Marked Learning Outcomes and by whom they were assigned.

NOTE: If the item contains multiple Marked Learning Outcomes, a separate object is returned for each Marked Learning Outcome.

Sections/Items/AssignedMarks/LearningOutcomes/Name string

The Marked Learning Outcome’s name.

Sections/Items/AssignedMarks/LearningOutcomes/Mark integer

The mark assigned for the Marked Learning Outcome.

Sections/Items/AssignedMarks/LearningOutcomes/MaxMark integer

The total available mark for the Marked Learning Outcome.

Error Codes

Refer to the following table for information on error codes that may be encountered when using this resource.

Name	Code	Description
InvalidKeycode	400	The specified keycode is invalid.
Unauthorized	401	There is an issue with the user specifying the request’s authentication details, or they do not have the relevant permission(s).
NoTestScriptFound	404	No test script was found for the specified keycode.
Unexpected	500	An unexpected error occurred.