ItemSet OAPI

Item sets are groups of items with “friend” relationships. Items with friend relationships cannot be added to a test without their friend items. Friend items always appear next to each other in tests and can share source material and question text, making them ideal for presenting a number of items on the same theme (such as in a case study).

The ItemSet OAPI resource is used to create and update item sets. If item language variants are enabled, you can also use the ItemSet OAPI to create and update item set language variants.

This article explains what calls can be made to the Surpass OAPI using the ItemSet resource.

Import this API into your Postman Workspace

Creating an item set

post /oapi/ItemSet

Send a request to the endpoint to create an item set.

If item language variants are enabled, you can also use the ItemSet OAPI to create specific item language variants of an item by passing a LanguageVariant path parameter in the request’s header.

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.

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
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`	Determines data format of the response (JSON).
LanguageVariant	path OPTIONAL	`/oapi/ItemSet/{id}/LanguageVariant`	Creates a new item set language variant for the specified item set, where `{id}` is the item set’s unique identifier and the item set’s language code is specified in the request body. NOTE: Item language variants are not available by default. If you would like item language variants enabled on your Surpass instance, contact your Surpass Account Manager.

Sample request

The following request contains the minimum required request body to create an item set.

{
    "subject": {
        "reference": "Subject1"
    },
    "name": "Item Set 1"
}

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

NOTE: If creating an item set language variant by passing a LanguageVariant path parameter in the request's header, name, parentId, locked, allowRandomisation, owner, items, subject, tagGroups, and enemyItems cannot be included in the request body.

name string mandatory

The item set’s name.

parentId integer optional

If the item set is in a folder, the folder’s unique identifier.

locked Boolean optional

Determines whether the Fix the order of items setting is enabled. If true, the order of items in the item set cannot be rearranged.

allowRandomisation Boolean optional

Determines whether the Allow randomisation of item set setting is enabled. If true, the order of the items in the item set can be randomised when creating a test.

owner object optional

The item set owner’s information.

owner/id integer

The item set owner’s unique identifier.

owner/reference string

The item set’s unique reference code.

items array optional

Contains any items in the item set.

NOTE: If the item set contains multiple items, pass a separate object for each item.

items/id integer

The item’s unique identifier.

items/position integer

The item’s position in the item set.

sourceMaterials array optional

Contains any source material attached to the item set.

NOTE: If the item set contains multiple source materials, pass a separate object for each source material.

sourceMaterials/id integer

The source material’s unique identifier.

sourceMaterials/externalId string

The source material’s name in Surpass.

sourceMaterials/type enumeration

The type of media, Image or Video.

sourceMaterials/width integer

The media’s width in pixels.

sourceMaterials/height integer

The media’s height in pixels.

stemComponents array optional

A collection of text, images or equations that form the item set’s shared text.

stemComponents/contentType enumeration

Determines the content type for the shared text. This can be either RichText, an Image, or MathML (Mixed subjects only).

stemComponents/content string

The shared text’s content in HTML format.

mediaItems array optional

Contains any media embedded on the item set.

NOTE: If the item contains multiple pieces of embedded media, pass a separate object for each piece of media.

mediaItems/id integer

The media’s unique identifier.

mediaItems/externalId string

The media’s external reference.

mediaItems/type enumeration

The type of media, Image or Video.

mediaItems/width integer

The media’s width in pixels.

mediaItems/height integer

The media’s height in pixels.

comment object optional

Contains the information of any comment left on the item set.

comment/text string

Any comment left on the item set in text format.

comment/isPrivate Boolean

Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not. Defaults to false if omitted.

language object optional

If item language variants are enabled and the LanguageVariant path parameter is passed in the request’s header, contains the information for the new item set language variant.

language/code enumeration

The language’s ISO code. The available language codes are amh, ar, arm, pob, bul, mya, zh, zho, hrv, ces, dan, nl, en-int, en, us, est, per, tgl, fin, frc, ga, gle, glg, ge, gre, heb, hun, ind, ita, jpn, kk, khm, kor, lao, la, lav, lit, mlt, mon, nep, no, pol, por, iir, ron, rus, smo, slk, slv, som, sp, es-int, lac, es-pa, es-pr, swe, tha, tur, ukr, vie, and we.

subject object mandatory

Contains the subject that the item set is in.

subject/id integer

The subject’s unique identifier.

subject/reference string

The subject’s unique reference code.

tagGroups

Contains the information of any tags assigned to the item set.

NOTE: To assign multiple tag values from multiple tag groups to the item set, pass a separate object for each tag group.

tagGroups/id integer

The tag group’s unique identifier.

tagGroups/name string

The tag group’s name.

tagGroups/tagCategories array

Contains the information of any tag categories the tag group is in.

NOTE: This property is not currently supported and will not assign any tag groups to a defined tag category.

tagGroups/tagValues array

Contains the information of the tag value(s) assigned to the item set.

NOTE: To assign multiple tag values to the item set, pass a separate object for each tag value.

tagGroups/tagValues/id integer

The tag value’s unique identifier.

tagGroups/tagValues/value string

The tag value.

tagGroups/tagValues/isItemSetTag Boolean

If true, the tag value is inherited from the item set.

NOTE: This property is not applicable to item sets.

tagGroups/tagValues/collection object

Contains the information of any tag collections the tag value is in.

NOTE: To add the tag value to multiple tag collections, pass a separate tag group object for each tag collection.

tagGroups/tagValues/collection/id integer

The tag collection’s unique identifier.

tagGroups/tagValues/collection/reference string

The tag collection’s unique reference code.

tagGroups/tagValues/collection/name string

The tag collection’s name.

tagGroups/tagValues/collection/order integer

The tag collection’s position within the tag collection group.

tagGroups/tagValues/collection/isCurrent Boolean

Determines whether the tag collection is the latest tag collection. Only the latest tag values can be returned when searching for items in Item Search.

tagGroups/tagValues/collection/collectionGroup object

Contains the tag collection’s tag collection group information.

tagGroups/tagValues/collection/collectionGroup/id integer

The tag collection group’s unique identifier.

tagGroups/tagValues/collection/collectionGroup/reference string

The tag collection group’s unique reference code.

tagGroups/tagValues/collection/subCollection object

Contains the information of any subcollections the tag value is in.

tagGroups/tagValues/collection/subCollection/reference string

The subcollection’s unique reference code.

tagGroups/tagValues/collection/subCollection/name string

The subcollection’s name.

tagGroups/tagValues/collection/subCollection/order integer

The subcollection’s position within the subcollection group.

tagGroups/tagValues/subCollection/collectionGroup object

Contains the subcollection’s subcollection group information.

tagGroups/tagValues/subCollection/collectionGroup/id integer

The subcollection group’s unique identifier.

tagGroups/tagValues/subCollection/collectionGroup/reference string

The subcollection group’s unique reference code.

tagGroups/isDeleted Boolean

Determines whether the tag group has been deleted.

enemyItems array optional

Contains the information of any items the item set has an enemy relationship with.

enemyItems/id integer

The item’s unique identifier.

enemyItems/isSectionOnly Boolean

Determines whether the enemy relationship is section-level (true) or test form-level (false).

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new item set’s details.

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Updating an item set

put /oapi/ItemSet/{id}

Send a request to the endpoint to update an item set. The item set’s name, settings, owner, items, source materials, shared text, media, and comments can be updated using this endpoint.

If item language variants are enabled, you can also use the ItemSet OAPI to update specific item language variants of an item by passing a LanguageVariant path parameter in a request’s header.

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
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`	Determines data format of the response (JSON).
id	path MANDATORY	`/oapi/ItemSet/{id}`	Updates specified item set, where `{id}` is the item set’s unique identifier.
languageCode	path OPTIONAL	`/oapi/ItemSet/{id}/LanguageVariant/{languageCode}`	Updates a specific item set language variant for the specified item set, where `{id}` is the item set’s unique identifier and `{languageCode}` is the language variant’s ISO code. NOTE: Item language variants are not available by default. If you would like item language variants enabled on your Surpass instance, contact your Surpass Account Manager.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

NOTE: If updating an item set language variant by passing a languageCode path parameter in the request's header, name, parentId, locked, allowRandomisation, owner, and items cannot be included in the request body.

name string

The item set’s name.

parentId integer

If the item set is in a folder, the folder’s unique identifier.

locked Boolean

Determines whether the Fix the order of items setting is enabled. If true, the order of items in the item set cannot be rearranged.

allowRandomisation Boolean

Determines whether the Allow randomisation of item set setting is enabled. If true, the order of the items in the item set can be randomised when creating a test.

owner object

The item set owner’s information.

owner/id integer

The item set owner’s unique identifier.

owner/reference string

The item set’s unique reference code.

items array

Contains any items in the item set.

NOTE: If the item set contains multiple items, pass a separate object for each item.

items/id integer

The item’s unique identifier.

items/position integer

The item’s position in the item set.

sourceMaterials array

Contains any source material attached to the item set.

NOTE: If the item set contains multiple source materials, pass a separate object for each source material.

sourceMaterials/id integer

The source material’s unique identifier.

sourceMaterials/externalId string

The source material’s name in Surpass.

sourceMaterials/type enumeration

The type of media, Image or Video.

sourceMaterials/width integer

The media’s width in pixels.

sourceMaterials/height integer

The media’s height in pixels.

stemComponents array

A collection of text, images or equations that form the item set’s shared text.

stemComponents/contentType enumeration

Determines the content type for the shared text. This can be either RichText, an Image, or MathML (Mixed subjects only).

stemComponents/content string

The shared text’s content in HTML format.

mediaItems array

Contains any media embedded on the item set.

NOTE: If the item contains multiple pieces of embedded media, pass a separate object for each piece of media.

mediaItems/id integer

The media’s unique identifier.

mediaItems/externalId string

The media’s external reference.

mediaItems/type enumeration

The type of media, Image or Video.

mediaItems/width integer

The media’s width in pixels.

mediaItems/height integer

The media’s height in pixels.

comment object optional

Contains the information of any comment left on the item set.

comment/text string

Any comment left on the item set in text format.

comment/isPrivate Boolean

Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not. Defaults to false if omitted.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new item set’s details.

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Error Codes

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

Code	Description
400	Indicates one of the following issues: There is an issue with the query parameters. Item set is locked by another user. Item set cannot be created. Item set cannot be updated.
401	The request has been sent by an unauthorised user.
403	Item set cannot be accessed.
404	Item set does not exist.

ItemSet OAPI

In This Article

Creating an item set

Parameters

Sample request

Request body schema

Sample response

Updating an item set

Parameters

Sample request

Request body schema

Sample response

Error Codes

Further reading

About the site