Thesaurus Management

A Thesaurus is a controlled list of terms. It can be used to construct lists of people, locations, titles, production houses etc. A thesaurus lives on the account level and is available to the workspaces in that account.

Custom fields or form fields can be configured to use this thesaurus to control the list of values which is allowed to enter in the field, and to suggest values.

Property Reference

See Thesaurus

Calls to manage thesauri

A thesaurus lives on the account level.

Create a thesaurus

POST /account/{accountId}/thesaurus

__

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long
Body Parameters
Name Description Required Type

body

✘

Object

body

Field Name

Required

Type

Description

Format
Return Type

✘

Content Type

  • application/json

Responses
Table 1. http response codes
Code Description Datatype

0

default response

``

The body is of type Thesaurus.

Updating a thesaurus

PUT /account/{accountId}/thesaurus/{id}

__

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long

id

ID of the thesaurus.

✔

Long
Body Parameters
Name Description Required Type

Thesaurus

✘

Thesaurus

Thesaurus

Field Name Required Type Description Format

accountId

✘

Long

int64

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

formFieldsDefinition

✘

FormFieldsDefinition

id

✔

Long

The id of this resource

int64

label

✘

String

lastUpdated

✘

Date

The time when this resource was last updated

date-time

linkedThesaurus

✘

Thesaurus

linkedThesaurusId

✘

Long

int64

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

secondaryId

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Return Type

Thesaurus

Field Name Required Type Description Format

accountId

✘

Long

int64

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

formFieldsDefinition

✘

FormFieldsDefinition

id

✔

Long

The id of this resource

int64

label

✘

String

lastUpdated

✘

Date

The time when this resource was last updated

date-time

linkedThesaurus

✘

Thesaurus

linkedThesaurusId

✘

Long

int64

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

secondaryId

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Content Type

  • application/json

Responses
Table 2. http response codes
Code Description Datatype

0

default response

Thesaurus

The body is of type Thesaurus.

Patching a thesaurus

To only update a specific property of the thesaurus, use JSON Patch:

PATCH /account/{accountId}/thesaurus/{id}

__

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long

id

ID of the thesaurus.

✔

Long
Body Parameters
Name Description Required Type

body

✘

Object

body

Field Name

Required

Type

Description

Format
Query Parameters
Name Description Required Type

version

✘

Long
Return Type

Thesaurus

Field Name Required Type Description Format

accountId

✘

Long

int64

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

formFieldsDefinition

✘

FormFieldsDefinition

id

✔

Long

The id of this resource

int64

label

✘

String

lastUpdated

✘

Date

The time when this resource was last updated

date-time

linkedThesaurus

✘

Thesaurus

linkedThesaurusId

✘

Long

int64

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

secondaryId

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Content Type

  • application/json

Responses
Table 3. http response codes
Code Description Datatype

0

default response

Thesaurus

Deleting a thesaurus

DELETE /account/{accountId}/thesaurus/{id}

__

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long

id

ID of the thesaurus.

✔

Long
Return Type

Thesaurus

Field Name Required Type Description Format

accountId

✘

Long

int64

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

formFieldsDefinition

✘

FormFieldsDefinition

id

✔

Long

The id of this resource

int64

label

✘

String

lastUpdated

✘

Date

The time when this resource was last updated

date-time

linkedThesaurus

✘

Thesaurus

linkedThesaurusId

✘

Long

int64

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

secondaryId

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Content Type

  • application/json

Responses
Table 4. http response codes
Code Description Datatype

0

default response

Thesaurus

Managing entries of a thesaurus

Property Reference

See ThesaurusEntry

Adding entries to a thesaurus

POST /account/{accountId}/thesaurus/{id}/entry

__

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long

id

ID of the thesaurus.

✔

Long
Body Parameters
Name Description Required Type

ThesaurusEntry

✘

List of ThesaurusEntry

ThesaurusEntry

Field Name Required Type Description Format

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

customFields

✘

CustomFields

formFieldValues

✘

Object

id

✔

Long

The id of this resource

int64

label

✘

String

lastUpdated

✘

Date

The time when this resource was last updated

date-time

linkedThesaurusEntryId

✘

String

modifiedBy

✔

String

The request or process responsible for the last update of this resource

objectType

✘

String

The data model type or class name of this resource

thesaurusId

✘

Long

int64

value

✘

String

version

✔

Long

The version of this resource, used for Optimistic Locking

int64
Return Type

✘

Content Type

  • application/json

Responses
Table 5. http response codes
Code Description Datatype

0

default response

``

Listing entries

GET /account/{accountId}/thesaurus/{id}/entry

List account entries in a thesaurus.

Details
Description

Returns the search result. This call makes use of Solr query parameters. For more info on those, checkout Solr Query parameters .

Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long

id

ID of the thesaurus.

✔

Long
Return Type

ThesaurusSolrDocumentList

Field Name Required Type Description Format

elapsedTime

✘

Long

int64

facetDates

✘

List of FacetField

facetFields

✘

List of IFacetField

facetPivot

✘

Map of object

facetQuery

✘

Map of integer

int32

facetRanges

✘

List of object

fieldStatsInfo

✘

Map of IFieldStatsInfo

groupResponse

✘

GroupResponse

highlighting

✘

Map of map

items

✘

List of Component

mediaObjectProperties

✘

Map of map

numFound

✘

Long

int64

responseHeader

✘

Map of object

results

✘

List of SolrDocument

start

✘

Long

int64

termsResponse

✘

TermsResponse
Content Type

  • application/json

Responses
Table 6. http response codes
Code Description Datatype

200

The request was successful.

ThesaurusSolrDocumentList

403

The user needs account manage rights.

ForbiddenError

404

The account or thesaurus was not found.

NotFoundError

Deleting an entry

DELETE /account/{accountId}/thesaurus/{id}/entry/{entryId}

__

Details
Description
Parameters
Path Parameters
Name Description Required Type

accountId

ID of the account.

✔

Long

id

ID of the thesaurus.

✔

Long

entryId

ID of the thesaurus entry.

✔

String
Return Type

✘

Content Type

  • application/json

Responses
Table 7. http response codes
Code Description Datatype

0

default response

``

Linked thesauri

A thesaurus can be linked to another thesaurus to introduce a level of hierarchy. Let’s say we have a thesaurus "genres" containing production genres like "Documentary", "Fiction" and "Sport". We also have another thesaurus "subgenres" containing subgenres like "Action", "Crime", "Football", "Tennis". Not all subgenres are applicable to all genres. When a user chooses the genre "Sport" we only want to suggest subgenres like "Football" and "Tennis", but not "Crime".

To make this work, the "subgenres" Thesaurus will set its linkedThesaurusId property to the id of the "genres" thesaurus.

Now, each Thesaurus Entry in "subgenres" can have a linkedThesaurusEntryId property. For the example above, the linkedThesaurusEntryId of the "Football" entry would be equal to the id of the "Sport" entry of the genres thesaurus.

Forms in the user interface built using custom fields or form fields will respect this relation, and only suggest applicable entries. Both fields should be shown in the form, though, for this to work.

Storing data on thesauri entries

You might have noticed a Thesaurus has a formFieldsDefinition property and a Thesaurus Entry has a formFieldValues property. It is possible to define extra data fields that each Thesaurus Entry will have. For example, one can attach gps coordinates to entries in a locations thesaurus.

Learn more about Form Fields

Thesaurus entries also contain a customFields property. This should be considered deprecated and use of it is strongly discouraged for new thesauri.