Item Resource

Item Resource

In Surpass, an item is a question or a survey that was authored by a user in the Item Authoring screens. In the user interface these items are then added to a test form which is scheduled and delivered to a candidate during a test session. This API resource supports all of the functionality that is available in the user interface for the majority of question types providing an effective method of migrating items into Surpass or using Surpass as an authoring tool and then exporting the items to use externally.  

Surpass offers a vast amount of authoring capability so this article will focus on the available methods including: information on how to build a POST request, mutual properties between question types, information on DELETE requests the permissions required for a successful request. A separate article will then define each individual question type with examples of the response and request for the GET/{id} and POST methods and a list of properties for each question type as this will differ based on which was selected. Please use the list below to go directly to these articles:

Available Methods


Below we have listed the operations, HTTP verbs and an example URL for each of the available methods for the Item Resource within the Surpass API. This information can be used when building your requests to this resource.
Operation HTTP Verb Example URL
Filter and Search GET https://...surpass.com/api/v2/Item?$filter=subject/reference eq 'Subject Reference'
Read (Individual by ID) GET/{id} https://...surpass.com/api/v2/Item/1
Create POST https://...surpass.com/api/v2/Item/
Update PUT https://...surpass.com/api/v2/Item/1
Remove DELETE https://...surpass.com/api/v2/Item/1

Building the POST Item Request

Successful POST requests to the Item Resource will require the body of the request to be built using the mandatory mutual properties (identified in the table below) and by providing a particular question type collection as part of the request as a minimum. This is because an item in Surpass can only be created once a question type is selected. Additionally "Draft" items require a different set of validation to "Live" items (available for delivery), this information will be highlighted in the table below and for each question type.

A simple example of the structure has been provided below:

POST https://...surpass.com/api/v2/item/

{
"subject":{
                "reference": "Subject Reference"
},
"name": "Item Name",
"multipleChoiceQuestions": [
                {
                }
   ]
}


Here the mutual properties "subject" and "name" have been defined and then the question type "multipleChoiceQuestions" has been selected. This would result in a blank MCQ question being created in Surpass.   




Properties for the Item Resource

Every item in Surpass is defined as a particular question type so the model required/returned from the API can vary depending on this, please use the required mutual properties from the table below and add the necessary collection for the question type. Below we have defined the property name, type, description, filterable (GET) and if the property is mandatory (POST).

Property Name Type Description Default Value
(POST)
Filterable
(GET)
Mandatory for
create (POST)
id int Unique Item Authoring ID, this is the suffix of the publish ID. Not available in POST/PUT. n/a
href string The URL to GET the individual item. Not available in POST/PUT. n/a
folder resource The folder in which the item is located within the subject.
Root Directory, null
folder / id int The unique id of the folder n/a
folder / href string The URL to GET the individual folder. Not available to POST n/a
folder / position int The position within the folder. First
itemType enumeration This property defines the type of the item. The same question type collections are used for Survey items, however only essay, MRQ and MCQ are supported. 
Available values: "Question", "Survey"
Question

subject resource The subject in which the item is located. n/a X X
(Draft)
subject / id int The unique id of the subject. n/a
subject / reference string The reference of the subject. n/a
subject / href string The URL to get the individual subject. Not available to POST. n/a
markSchemeFieId int The id of the mark scheme uploaded to the item. null
markSchemeFileName string The file name of the mark scheme attached to the item. null
name string The name of the item. n/a X X
(Draft)
publishId string The unique Surpass id that publishes to Test Creation. n/a
itemMajorVersion int If Version Compare is enabled in CMS, then there will be Major Versions and Versions of items. The major version of the item occurs with any significant change - status, owner, and any changes made at live status. n/a
itemVersion int The version of the item. n/a
deleted boolean The value identifies if the item is in the recycle bin. false
questionText HTML The question stem in HTML format. This will only return the first stem block if multiple are specified. Stem components returns all stem blocks. null
htmlText HTML The question stem in HTML format. This will only return the first stem block if multiple are specified. Stem components returns all stem blocks. null
mathML MathML Formula can be added to the question stem using this property or returned if this was authored in the user interface. It must be passed in using valid MathML. null
assistiveMedia  object This object refers to assistive media that can be assigned to the question text to help provide an alternative method of providing the question text to the candidate e.g. in audio format.  null
assistiveMedia / id   int The id of the assistive media within the context of the question item. n/a
assistiveMedia / href   string The request URL required to return the assistive media file in its encoded format. n/a
mark int The mark assigned to the item. 0
seedUsageCount int Provides the ability to create an Item with a previous usage count. null
seedPValue int Provides the ability to create an Item with a previous P value. null
status enumeration The items workflow status. Available values: 'Draft', 'To Review', 'Reviewed', 'Live'. Draft
itemPurpose enumeration The purpose of the item can be assigned to an item. Available values: 'Summative', 'Formative', 'Unspecified'. Unspecified
markingType enumeration The method of marking the item. Available values: 'Human', 'Computer'. Computer
comment string The comments made on the item. This will be returned as a comma separated list. null
generalFeedback object Any general feedback attached to the item. Only general or correct / incorrect feedback can be assigned to an item. null
generalFeedback / text HTML The text included in the general feedback in HTML format. n/a
generalFeedback / htmlText HTML The text included in the general feedback in HTML format. Retired property. null
generalFeedback / mediaItems resource Any media associated to the general feedback. null
generalFeedback / mediaItems / id int The id of the media associated to the general feedback
This id relates to the media resource.
n/a
generalFeedback / sourceMaterials resource Any source material associated to the general feedback. null
generalFeedback / sourceMaterials / id int The id of the source material associated to the general feedback. This id relates to the media resource. n/a
correctFeedback object Any correct feedback assigned to the item for formative feedback during the test. Only supported in computer marked questions. null
correctFeedback / text HTML The text included in the correct feedback in HTML format. n/a
correctFeedback / htmlText HTML The text included in the correct feedback in HTML format, Retired property. null
correctFeedback / mediaItems resource Any media associated to correct feedback. null
correctFeedback / mediaItems / id int The id of the media associated to the correct feedback.
This id relates to the media resource.
n/a
correctFeedback / sourceMaterials resource Any source material provided in correct feedback. null
correctFeedback / sourceMaterials / id int The id of the source material provided in correct feedback.
This id relates to the media resource.
n/a
incorrectFeedback object Any incorrect feedback attached to the item for formative feedback during the test. Only supported in computer marked questions. null
incorrectFeedback / text HTML The text included in the incorrect feedback in HTML format. n/a
incorrectFeedback / htmlText HTML The text included in the incorrect feedback in HTML format. Retired property. null
incorrectFeedback / mediaItems object Any media associated to the incorrect feedback null
incorrectFeedback / mediaItems / id int The id of the media associated to the incorrect feedback.
This id relates to the media resource.
n/a
incorrectFeedback / sourceMaterials object Any source material provided in the incorrect feedback null
incorrectFeedback / sourceMaterials / id int The id of the source material provided in the incorrect feedback.
This id relates to the media resource.
n/a
mediaItems resource Any media that is embedded into the item null
mediaItems / id int The id of the embedded media. This id relates to the media resource. n/a
sourceMaterials resource Any source material attached to the item. null
sourceMaterials / id int The id of the source material. This id relates to the media resource. n/a
stemComponents collection A collection of text, images or equations that make up the question text. These will be added directly after one another rather than inline. This property is expected to be used rather than questionText.
Only text, media or MathML can be supplied in each object, media is not allowed in the first object to follow UI validation.
n/a X
(Live)
stemComponents / text HTML Text included in the question stem. Formatting can be applied using HTML. null
stemComponents / mathMl MathML Formula can be added to the question stem using this property or returned if this was authored in the user interface. It must be passed in using valid MathML.   null
stemComponents / media resource Any media embedded into the question stem. null
stemComponents / media / id int The id of the media embedded into the question stem.
This id relates to the media resource.
n/a
allowOpenImageInPopup boolean If the Item contains media this option will allow the image to be opened in a popup window. false
mediaLayout enumeration The location of the media. AutoSelect
itemSet resource The Item Set that the item is in. null
itemSet / id int The ID of the Item Set. null
itemSet / href string The URL of the Item Set. null
itemSetTagValues resource Any tags values that have been associated at the Item Set level. null
itemSetTagValues / id int The ID of tags values that have been associated with the item at the Item Set level. null
itemSetTagValues / href string The URL of the tags values that have been associated with the item at the Item Set level. null
itemTagValues resource Any tags that have been associated to the item. null
itemTagValues / id int The id of the tag value association. n/a
itemTagValues / href string The URL to get individual information regarding the item tag value association. n/a
enemyItems collection A collection of items/item sets that have have been identified as an enemy when authoring this question. These items will not appear in the same test. null
enemyItems / id int The ids of any items/item sets identified as an enemy to the returned item.  n/a
enemyItems / href string The request URL required to return information regarding an enemy item/item set. n/a
secondaryEnemyItems collection A collection of acquired enemy items/item sets, the enemy item relationship has been assigned on this item rather than the one returned.  null
secondaryEnemyItems / id int The ids of any items/item sets that have marked this item as an enemy.  n/a
secondaryEnemyItems / href string The request URL to return information regarding this enemy item/item set. n/a
sectionEnemyItems / id string An item that has a section enemy. This will return the ID for the item/item set that the particular item is a section enemy with. A section enemy is an item/item set that can appear in the same test, but not the same section. This is not available by default. n/a
tools collection A collection of tools that can be used on the item specified. This currently only supports calculator. null
tools / name enumeration The name or type of tool. Currently only calculator is supported null
tools / settings variable object An object that allows any specific tool settings to be set. Calculator currently has the following setting properties:
"mode":"basic | scientific"
"label": "Calculator label"
null
owner
int The id of the user who will become the Item Owner. Will default to the user who created the item if left blank. null
sharedWith resource The item has been shared with a subject master list. n/a
sharedWith / id
int The id of the subject master list the item has been shared with. n/a
sharedWith / reference
string The reference of the subject master list. n/a
sharedWith / href
string The URL to GET the subject the item has been shared with. n/a
standardLists
object The item is part of a standard item list. n/a
standardLists / id
int The id of the standard list the item belongs to. n/a
standardLists / reference
string The reference of the standard list. n/a
standardLists / href
string The URL to GET the standard list the item belongs to. n/a

GET Requests

The Item Resource on the Surpass API provides the ability to search and filter items based on parameters and properties passed into the request. This is done using a GET request and passing the properties as part of the query-sting in the request URL. The response from the request is slightly different to the GET/{id} where it returns a paged subset of the Items information, however this will provide the consumer with the information required to request the GET/{id} method. Below we have provided some examples:

GET Item - JSON Example
GET Item - XML Example 

The GET Item method also allows users to pass the parameter "includedDeleted":true as part of the request URL, if this is passed then items within the recycle bin will also be returned in the GET item response. 


PUT Requests


PUT Requests should reference the ID of the item you would like to update as part of the request URL. All properties are optional so you only need to provide this information within the body of the request, all other properties will retain their current values. Certain properties may require other ones to be specified as part of their validation, please see the table above and for the particular question type if you are receiving a validation error here. 


DELETE Requests

To delete an item via the Surpass API the request should be sent using the DELETE HTTP method and the URL should reference the ID of the item you want to delete. The first time this is sent Surpass will move the item to the recycle bin and therefore require another request to permanently delete the item. The response of the request will return the current state of the item in a boolean flag "permanentlyDeleted" so the consumer is aware of this state, this information is also available via the GET/{id} method using the "deleted" flag.

Assistive Media

In Surpass, assistive media allows the author to supply additional media items to the question text and answer options. This provides another method of providing the candidate with the information presented in an item. In test delivery this will be played to the candidate when they select an additional button. A good use case for this functionality is to provide candidates with recordings of the question stem.  

Using the Item Resource it is possible to include assistive media in the PUT or POST request by providing this in a base 64 encoded format. However the GET/{id} request will only provide the URL to retrieve each individual media item, this was put in place to not overload the Item response. It is therefore possible to edit or add assistive media via the below requests:

POST https://...surpass-preview.com/api/v2/Item/
PUT https://...surpass-preview.com/api/v2/Item/{ItemId}
PUT https://...surpass-preview.com/api/v2/Item/{itemId}/AssistiveMedia/{id}

The last request is useful if you want to update one answer option as the PUT Item request will require an explicit list of all options for a successful request.

Current functionality means that you are restricted to only uploading an mp3 of a maximum size of 1MB.

Required Permissions

To successfully call the Item methods, the user specified in the header of the request must have the "Item Writer", "Item Reviewer" or "Item Publisher" permission. The item status being sent must correspond to the users permission.

Feedback and Knowledge Base