ItemTagValue Resource

In Surpass, users have the ability to create tags which can be assigned to question items. These tags can be used to search for items within Item Authoring or as a rule to dynamically select items for tests based on tags that have been assigned. This can be used to build a test matrix which users then create fixed tests from or it can be used to always dynamically select items when it is delivered to candidates. All subjects have the default tag groups Learning Outcome, Unit, and Keywords, but additional custom tag groups can be created at the subject level.

Using the ItemTagValue Resource on the Surpass API, it is possible to create and delete associations between tag values and items in Surpass allowing you to automate the process of assigning these items in bulk rather than having to manually assign these in the user interface. The Item resource also provides the consumer with the ItemTagValue URL so the consumer can identify all the tags that have been assigned to an item.


ItemTagValue Resource

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

Operation HTTP Verb Example URL
Read (individual) GET https://...surpass.com/api/v2/ItemTagValue/1
Create POST https://...surpass.com/api/v2/ItemTagValue/
Remove DELETE https://...surpass.com/api/v2/ItemTagValue/

Properties of the ItemTagValue Resource

Within the table below we have provided all of the properties included in the ItemTagValue resource. This includes the property name, data type, and if it is mandatory when sending a POST request.

Property Name Type Description Mandatory
(POST)
id int The unique id of the association between the tag and the item. Not available to POST.
href string The URL to return all information about the association. Not available to POST.
tagValue resource The tag value that is being associated to the item
tagValue / id int The id of the tag value being associated to the item x
tagValue / href string The URL to return information regarding the tag value. Not available to POST.
tagValue / text string POST only. This allows the user to pass the tags value into the request as the identifier,
this must already exist as a valid tag before the request is successful.
tagValue / number number POST only. This allows the user to pass the tags value into the request as the identifier,
if the value does not already exist (for that Tag Group in that Subject), it is created and assigned to the item. The tag value must be inside the numerical range.
tagGroup resource The tag group the tag value belongs to
tagGroup / id int The id of the tag group x
item resource The item the tag value is being associated to.
item / id int The id of the item the tag value is being associated to. x
item / href string The URL to return all information about the item. Not available to POST.

GET Requests

The ItemTagValue resource on the Surpass API provides the ability for the consumer to read individual tag value to item associations by sending a GET request to the API specifying the ID as part of the request URL. The ID of the item tag value association can be found by requesting the GET/{id} on a particular item. Below we have provided some examples:

GET ItemTagValue - JSON Example

GET ItemTagValue - XML Example 


POST Request and Return

The POST ItemTagValue method requires the properties listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address and body of the request (for both formats) can be found below.  

Example POST request & response (JSON)

Example POST request & response (XML)


DELETE request and return

DELETE requests should use the ID of the item, tag value and tag group you want to delete. Successful deletes will return a status of 200 and will return the base resource with all values set to null. An example of the DELETE ItemTagValue request has been provided below.

DELETE https://...surpass.com/api/v2/ItemTagValue

{
  "item": {
    "Id": 14882
  },
  "tagValue": {
    "Id": 1583,
  },
  "tagGroup": {
    "Id": 764
  }
}

Required Permissions

To successfully call the ItemTagValue methods, the user specified in the header of the request must have the ‘Item Writer’, 'Item Reviewer' or 'Item Publisher' permission in Surpass and the item's status (that is included in the request) must match the users permission.

Feedback and Knowledge Base