1. Introduction

This is the REST API documentation for TermWeb 4.0.9-2. Here you’ll find how to work with API, common techniques and what to expect to receive from endpoints.

For more TermWeb information see the interverbumtech.com.
For high level information and installation instructions please see the documentation site.
For a demo of TermWeb 4 please write to us info@interverbumtech.com.

2. Assumptions

This documentation assumes a basic knowledge of how REST APIs work. For basic tutorials on REST API we recommend visiting REST API Tutorial.

3. Getting started

This API provides access to a variety of different resources including the following:

Terms
Users
Dictionaries
Projects
Workflows
Stemming
Term decoration
…​etc

To start using it, you need to build your own REST API client. You can start building client by generating it. To generate client you can use our web services definition openapi.yaml.

Service definition has been described by using OpenAPI Specification ver.3 (known as Swagger). For more information about this format please read this specification.

For better presentation of service definition you can use online swagger editor, which converts JSON or YAML files to human readable format https://editor.swagger.io/.

4. Authentication

TermWeb is using authentication token for securing API requests and cookie. Token for now must be sent in http header X-Auth-Token to all endpoints, except for /api/v4/login and /api/v4/system/features. Cookie JSESSIONID is set by server after passing login endpoint.

To obtain that token you need to use login endpoint.

POST /api/v4/login

Example request
curl 'https://localhost:8080/api/v4/login' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'client=admin&username=alexey&password=secret&language=eng' \
  --compressed
Response
Headers:
set-cookie: JSESSIONID=1234567890ABCDEF1234567890ABCDEF; Path=/; HttpOnly
{
  "token": {
    "token": "0000111100001111000011110001110", (1)
    "expirationTime": 1601363809513 (2)
  },
  "errorMessage": null
}
1 token here is value which must be sent as header X-Auth-Token with each next request.
2 expirationTime date and time up to which the token will be valid. Value is number of milliseconds since Unix Epoch.

5. Data pagination

Almost all top-level API endpoints have support for bulk fetches via "list" API methods.

These list API methods share a common signature, taking some of these parameters: page, size, and sort.

By default, TermWeb is configured to limit requested page size by 500. To change that value you can configure TermWeb server, see TermWeb configuration.

Parameters
Parameter Description

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
List response
Page object
{
  "content": [
    {
      "id": 12,
      "name": "Medical reference terminology"
    },
    {
      "id": 40,
      "name": "Wiki"
    },
    {
      "id": 61,
      "name": "Demo glossary"
    },
    {
      "id": 107,
      "name": "Wiki copy"
    },
    {
      "id": 108,
      "name": "Archive"
    }
  ],
  "last": false,
  "totalElements": 44,
  "totalPages": 9,
  "sort": null,
  "numberOfElements": 5,
  "first": true,
  "size": 5,
  "number": 0
}
Property Description

content Object[]

requested resources from endpoint

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

6. Old objects vs. New objects

TermWeb right now is a hybrid app containing some old pages in Administration view.

Because of that we have two structures of Data Transfer Objects (DTO).

Old objects always have values for the following attributes:

  • oid, string

  • id, number

New objects don’t have the oid attribute (or it can be set to null). Additionally, new objects have another extra attribute: version.

Most of the DTOs containing converted attributes, like dictionary_oid, or client_oid will be represented by dictionary_id and client_id.

The oid attribute is mostly provided for backward compatibility and should not be used in most cases.

7. Versioning

To avoid concurrent modifications problems, we’re using optimistic locking method.

To achieve that we’re providing "version" attribute with our DTOs. This "version" attribute must be sent always with update requests.

For new objects please use attribute version, for old objects please use value of changed.time.

When object has been updated on server, and you’re updating old version of it, you’ll receive response with http code: 409 (Conflict).

8. Metadata

Most of objects provided by API endpoints have information when it was created and by whom or when it was changed.

Also worth to mention that all top level objects have client_id attribute which is always has same value for single tenant installations, but has different values in multi tenant installations. client_id must always present in objects metadata.

Metadata attributes
Object attribute Properties Description

created Object

id number

User id created that object

name string

User login created that object

fullName string

User full name created that object

time number

Created date and time in milliseconds since Unix Epoch

oid string

User oid created that object (provided for backward compatibility)

changed Object

id number

User id changed that object

name string

User login changed that object

fullName string

User full name changed that object

time number

Last change date and time in milliseconds since Unix Epoch

oid string

User oid changed that object (provided for backward compatibility)

client_id number

Client id where object is stored

9. Errors and status codes

TermWeb uses standard HTTP response codes to provide the status of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error during processing of request (e.g., a required parameter was omitted, user don’t have enough of permissions, JSON object can’t be processed, etc.). Codes in the 5xx range indicate an error with TermWeb’s servers.

Some 4xx errors can be handled programmatically. Response body may include an error code and message which explains the error reported.

For security and privacy reasons some of endpoint methods can return 404 code instead of 403 to not disclose data stored in TermWeb.

HTTP code Description

200 - OK

Everything worked as expected

201 - Created

Create request has been successfully completed

202 - Accepted

Everything worked as expected, operation will continue in async mode

204 - No content

Object deletion complete, nothing to return

400 - Bad Request

Incorrect data has been submitted to endpoint method.

401 - Unauthorized

To process this request, request must contain authentication token. See Authentication.

403 - Forbidden

Current user doesn’t have enough permissions to perform this operation.

404 - Not found

Requested object with specific id or anything related to that object has not been found.
Requested objects which are marked as deleted, also will return 404 code unless, include-deleted param is not specified

405 - Method not allowed

Server can return this when you’re accessing a deleted experimental feature or providing an unsupported parameter.

409 - Conflict

Cannot update current version of object. Please merge your changes into new version of object and try to update it again. See Versioning.

422 - Unprocessable Entity

Can be returned when the server understands the request but cannot process it because an equal object already exists.

10. Date and time

All values representing date and time in JSON response sent from server is a number of milliseconds since January 1, 1970, 00:00:00 UTC represented by this value, or simply called Unix time (or milliseconds since Unix Epoch).

For example, to get proper value in JavaScript just create a new Date object:

const numberSinceUnixEpoch = 1601363809513;
const date = new Date(numberSinceUnixEpoch);
console.log(date.toString());

Date values must be provided as simple strings. Default format for dates is yyyy-MM-dd, e.g. 2020-07-20

Filters conditions can accept multiple formats: yyyy-MM-dd HH:mm:ss, yyyy-MM-dd HH:mm, yyyy-MM-dd, yyyyMMdd. Please note that these dates will be converted to the server’s time zone which is UTC by default.

11. User roles

TermWeb has four kinds of roles:

  • System Administrator - owner of installation with access to all clients. Can create new clients and doesn’t have any permission restrictions within any client.

  • Client Administrator - administrator for a single client. Can create and edit all other users except System administrators within their own client. Doesn’t have any permission restrictions within the client.

  • Dictionary Administrator - allows a user to administrate a specified dictionary. Allows user to change dictionary structure, workflows, projects etc.

  • User editor - allows the user to edit and update non-administrator user accounts.

Roles doesn’t have any database entities, only constant values: SYSADMIN, ADMIN, USEREDITOR, and dynamic values for dictionary administrators which combined from constant prefix and dictionary oid: DICTIONARY_ADMIN@ + <dictionary_oid>.

12. Object response formats

API endpoints can return objects in four different formats. Pick your format according to your needs.

Format key Description

ID

Search results will only contain object id and nothing else

SHORT

Search results will contain object id and some information like name and description. Useful for autocomplete searches and other things like this.

FULL Default

Search results will have all attributes, including id, name and metadata.

EDIT

Includes everything from FULL format plus extra objects needed for editing. This allows to speed up loading of all required objects for editing in one request.

• NamedObject interface

Server may return for some requests simplified form of object containing only object id and name.

Object attribute Description

name string

Name of object

oid string

Old object oid

13. API Reference

13.1. Authentication

13.1.1. Login

POST /api/v4/login

Description

Authenticates user in TermWeb and returns token.

Request documentation
Headers

Content-Type

application/x-www-form-urlencoded

Path parameters

Query parameters

Payload fields

client

<optional>, default is 'admin', or any other client login name in case of multitenant installation

username

user login

password

user password

language

<optional>, default is 'eng'
Example request
curl 'https://localhost:8080/api/v4/login' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'client=admin&username=alexey&password=secret&language=eng' \
  --compressed
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload fields

token TokenInfo

 
{
  "token": "0000111100001111000011110001110", (1)
  "expirationTime": 1601363809513 (2)
}
1 token value which must be sent as header X-Auth-Token with each next request.
2 expirationTime date and time up to which the token will be valid. Value is number of milliseconds since Unix Epoch.

errorMessage string

Message in case of error

13.1.2. Logout

POST /api/v4/logout

Description

Ends user session in TermWeb and releases authentication token.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

13.1.3. Logout user

POST /api/v4/logout-user

Description

Allows to administrators to end other users sessions.

Request documentation

Headers

X-Auth-Token

Unexpired authentication token

Request parameters

user-id

Id of User to end session.
Response documentation
Status

204 NO CONTENT

After finishing operation. To get update, check current online users via GET /api/v4/system/statistics/online-users.

13.1.4. Validate

GET /api/v4/validate

Description

Checks validity of current authentication token and returns result of that validation.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/application/json;charset=UTF-8

Payload fields

tokenValid boolean

true when token is still valid

13.1.5. Extend session

POST /api/v4/extend-session

Description

Checks if requested token is still valid and returns new expiration time in case of success, otherwise HTTP code 403.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload fields

expires number

date and time up to which the token will be valid. Value is number of milliseconds since Unix Epoch.

13.1.6. Switching client

POST /api/v4/switch-client

Description

In case of multitenant installation to start working with data from different client then current client you need switch that client for current authentication token or authenticate with different credentials.

To be able to switch client for user, that user must be mapped to that client or must be a system administrator.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Content-Type

application/json;charset=UTF-8

Payload

Request body

Body must contain only one value – client_id
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

User data Object

User data object specific to current user search settings for requested client
Example of User data from response
{
    "activeClientIds": [15],
    "clients": [{"oid": "1b5uct", "id": 34,…},…],
    "dictionaries": [{"oid": "eu5qu", "id": 181,…}, {"oid": "dr3sf", "id": 173,…}],
    "filters": [{"oid": "eq46e", "id": 583,…}],
    "isSystem": true,
    "permissions": {"quickFiltersEnabled": true, "searchModesEnabled": true,…},
    "preferences": {"id": 111, "version": 0, "userId": 96,…},
    "roles": [{"oid": "ADMIN", "id": 1, "version": 1,,…},…],
    "selectedTermNames": {},
    "settings": {"oid": "doogf", "id": 96, "userOid": "doogc",…},
    "stagingAreas": [{"id": 231, "version": 4,…}, {"id": 232, "version": 4,…},…],
    "user": {"oid": "doogc", "id": 96, "created": {"time": 1571742852639, "fullName": ""},…}
}

13.1.7. Reset password

POST /api/v4/reset-password

Description

Sends to user reset password link via email, if there is matching user with specified parameters.

Request documentation
Request parameters

username

username of User to look

client

loginName of Client to look in case of multi tenant installation
Response documentation
Status

200 OK

In case of successfully processing request.

13.2. System configuration

13.2.1. Clients endpoint

Description

Client object represents a set of data available only to users related to it. Users from other clients won’t be able to access that data unless system administrators provide it to them by giving mapping to that.

For single tenant installation this endpoint will provide only ability to edit default client object.

Major functions provided by this endpoint:

  • Only system administrators can edit clients

  • loginName - can contain only letters and digits, other values are not allowed.

  • loginName - should be unique for whole system

  • For existing client sysadmin can change only next fields: name, login name, max concurrent users, max concurrent guests, max user accounts, status.

  • For new client sysadmin also should be able to specify new administrator user credentials (login, full name, email, password). Interface should validate user password like in User editor component. Default values for login: admin, full name: Administrator.

  • API key should be shown as readonly string for existing client (for new client hide it).

  • System administrator should be able to generate new API key, for that render button right after API key with name 'Generate new API key'. When user presses on it, UI shows warning dialog which contains message, that all further connections with old API key won’t be able to login.

  • If Server license has limit on user accounts, then UI should not allow specify Max accounts value greater than available user limit.

  • If during Client creation maximum user value has been changed, then server will decrease max accounts automatically.

Clients list:

  • Filtering by name should work on two fields: login and full name.

  • System administrator should be able to sort list by Client name, login, users count, maxconcusers, maxconcguests, max accounts, status, created, modified.

  • System should be able to create new client

  • System administrator should be able to delete selected clients or client.

  • Deletion of client of current session should be not allowed.

DevNote:

to validate client login use /clients/find?loginName=

to generate new API key use /clients/generate-new-api-key/{clientId}

to get max possible value for max user count check property 'availableUserSlots' of License object.

• Client DTO
Object attribute Description

name string

Unique name of client.

active boolean

Current status of client.

loginName string

Unique login name for client. May contain only Latin letters and numbers.

apiKey string

API key for current client. Used in integrations via webservices.
Visible only to system and client administrators.

maxUsers number

Maximum number of users which can be created in that client.

maxGuests number

Maximum number of current guests which can login and work to that client.

maxConcurrentUsers number

Maximum number of users in total (names users + guests) which can login and work concurrently with that client.

currentUsersNumber number

Current number of named users for that client.

adminUser User

Can be used only with create method. Administrator login for new client. Simplified version of User.
You can specify for that User only this attributes: username, email, and password.

id number

Client id.

oid string

Client oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Available

GET /api/v4/clients/available

Description

Returns list of clients available for current authentication token.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client[]

Array of available clients of type Client.
• Generate new API key

POST /api/v4/clients/generate-new-api-key/{client-id}

Description

Resets old API key for client and creates new one.

Request documentation

Path parameters

client-id number

client id value
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

JSON object of Client.
• Find

GET /api/v4/clients/

Description

Finds clients with specified query parameters available to current user.

Request documentation

Query parameters

login-name string

<optional>, default is null
Filters clients with login name starting with provided value. Search will be case insensitive.

login-name-eq string

<optional>, default is null
Filters clients with login name equal to provided value ignoring case.

max-concurrent-users number

<optional>, default is null.
Looks for clients where maximum of concurrent users is equal to provided value.

max-user-accounts number

<optional>, default is null.
Looks for clients where maximum of user accounts is equal to provided value.

name string

<optional>, default is null
Filters clients with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters clients with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Client[]

Found clients of type Client.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/clients/rownum/{id}

Description

Finds rownumber of client with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Client id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

login-name string

<optional>, default is null
Filters clients with login name starting with provided value. Search will be case insensitive.

login-name-eq string

<optional>, default is null
Filters clients with login name equal to provided value ignoring case.

max-concurrent-users number

<optional>, default is null.
Looks for clients where maximum of concurrent users is equal to provided value.

max-user-accounts number

<optional>, default is null.
Looks for clients where maximum of user accounts is equal to provided value.

name string

<optional>, default is null
Filters clients with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters clients with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/clients/{id}

Description

Looks for client with specified id.

Request documentation

Path parameters

id number

Client id to look for

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

JSON object of Client.
• Create

POST /api/v4/clients/

Description

Creates new client from JSON data sent in payload.

Request documentation

Payload

body Client

JSON object of type Client.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

Created object of client.
• Update

PUT /api/v4/clients/{id}

Description

Updates existing client from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Client which need to be updated

Payload

body Client

JSON object of type Client. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

Updated client object.
• Partial update

PUT /api/v4/clients/partial/{id}

Description

It updates only specified parts of client from JSON data sent in payload. Unlike method PUT /api/v4/clients/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Client which need to be updated

Payload

body Client

JSON object of type Client. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for client objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Client

Patched client object.
• Delete

DELETE /api/v4/clients/{id}

Description

Deletes client with specified id.

Request documentation

Path parameters

id number

Client id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/clients/async/{id[]}

Description

Deletes clients with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Client ids of clients to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is client id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.2.2. API Synchronization settings endpoint

Description

In this UI administrators will be able to select a dictionary and see list of relevant languages/language variants with checkboxes. They will be able to select there which of these languages/language variants that are to be synchronized to the TermWeb Integrator and apply this setting to user groups.

A translator would thus install the TermWeb Integrator, enter the credentials and as they select dictionary for synchronization, only receive the relevant languages/language variants (locales) in Multiterm DB format (based on the setting in TermWeb as presented above). This will guarantee that they only see what they need to.

• APISyncSettings DTO
Object attribute Description

name string

Unique name of API sync settings object.

description string

Description for API sync settings object.

active boolean

Current status of API sync settings object.

dictionaryId number

Dictionary id of the corresponding dictionary.

languages LangMapping[]

List of languages to which this API sync settings applied. See LangMapping.

groups GroupMapping[]

List of groups to which this API sync settings applied. See GroupMapping.

filter Filter

<optional>, Set of conditions applied to this API sync settings. See Filter.

clientId number

Client id to which object belongs

id number

API synchronization settings id.

version number

API synchronization settings version number. Represents latest modification counter.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• LangMapping
Object attribute Description

langCode string

Code of one of the languages from dictionary related to API sync settings.

regionCode string

Code of one of the region from language of dictionary related to API sync settings.

scriptCode string

Code of one of the script from language of dictionary related to API sync settings.
• GroupMapping
Object attribute Description

groupId number

Group id.
• Find

GET /api/v4/sync-settings/

Description

Finds API sync settings with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter API sync settings objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters API sync settings with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters API sync settings with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content APISyncSetting[]

Found API sync settings of type APISyncSettings.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/sync-settings/rownum/{id}

Description

Finds rownumber of API sync settings with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

API synchronization settings id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter API sync settings objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters API sync settings with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters API sync settings with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/sync-settings/{id}

Description

Looks for API sync settings with specified id.

Request documentation

Path parameters

id number

API synchronization settings id to look for

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body APISyncSetting

JSON object of API synchronization settings.
• Create

POST /api/v4/sync-settings/

Description

Creates new API sync settings from JSON data sent in payload.

Request documentation

Payload

body APISyncSetting

JSON object of type APISyncSettings.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APISyncSetting

Created object of API sync settings.
• Update

PUT /api/v4/sync-settings/{id}

Description

Updates existing API sync settings from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of API synchronization settings which need to be updated

Payload

body APISyncSetting

JSON object of type APISyncSettings. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APISyncSetting

Updated API sync settings object.
• Partial update

PUT /api/v4/sync-settings/partial/{id}

Description

It updates only specified parts of API sync settings from JSON data sent in payload. Unlike method PUT /api/v4/sync-settings/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of API synchronization settings which need to be updated

Payload

body APISyncSetting

JSON object of type APISyncSettings. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for API sync settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APISyncSetting

Patched API sync settings object.
• Delete

DELETE /api/v4/sync-settings/{id}

Description

Deletes API sync settings with specified id.

Request documentation

Path parameters

id number

API synchronization settings id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/sync-settings/async/{id[]}

Description

Deletes API sync settings with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

API synchronization settings ids of API sync settings to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is API sync settings id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.2.3. API Templates endpoint

Description

Here, you create templates to be used by different customers, stating what dictionary/dictionaries (or section/sections) to use for lookup and possible term suggestions e.g. for different customers in the XTM Cloud or Trados Studios Plugin.

In a template the following settings can be configured:

  • A list of dictionaries where to search in. This option selects all sections of this dictionary and makes section selection of the same dictionary redundant.

  • A list of sections where to search in.

• APITemplate DTO
Object attribute Description

name string

Unique name of API template object.

description string

Description for API template object.

dictionaryIds number[]

An array Dictionary ids used by this template.

sectionIds number[]

An array Section ids used by this template.

showDeprecatedTerms boolean

true when API template configured to return deprecated terms in term decoration results. When Dictionary uses TBX field administrativeStatus known as Usage status and field value is Not recommended or Obsolete this Terms also will be marked as deprecated. After TermWeb will check next Field value specified by name from deprecatedFieldName.

deprecatedFieldName string

Name of Field used to determine is Term deprecated or not.

deprecatedValue string

Value of deprecatedFieldName used to determine is Term deprecated or not.

showAcceptedTerms boolean

true when API template configured to return deprecated terms in term decoration results.

acceptedFieldName string

Name of Field used to determine is Term approved or not.

acceptedValue string

Value of acceptedFieldName used to determine is Term approved or not.

settings APITemplateSettings

Additional settings. See APITemplateSettings.

clientId number

Client id to which object belongs

id number

API Template id.

oid string

API Template oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• APITemplateSettings
Object attribute Description

regionMatchMode enum

Possible values are:

  • IGNORE_REGION

    • Region codes from term decoration requests (XTM, Trados studio) will be ignored and matched to any terms in a base language. This is the same implementation used for TermWeb 4.0.7-1 and earlier. Ex) “eng-us” → “eng”

    • In the case of Custom language codes, these will try to be matched first. Ex) “eng-us” → “eng-us”

  • ONLY_MATCHING

    • Strict matching. Only matches Region with Geographical variant or Custom language code. Ex) “eng-us” → “eng-us”

  • FALLBACK_TO_PARENT

    • Strict matching but with fallback. Will try and match strictly but if no match is found it will return all other variants, including non-regional variants. Ex) “eng-us” → “eng-us” → “eng”

stemComparisonMargin number

The margin of characters allowed to be different at the end of a stem during stem comparison in decoration.
The default value is 0 and it means that the stems need to be 100% identical.

stemMinimumLength number

The limit of characters where a word should be considered as a stem during decoration. 1 is default.

returnTermsWithPunctuation boolean

By default, TermWeb term decoration function skips from results terms containing next punctuation symbols: . , ! ? : ; . You may include this terms by changing this value to true.

termsHashtagEnable boolean

Handles hashtag terms as normal terms. Includes them in decoration for segments that contain or not, the hashtag.

handleSpaceTags boolean

Handles some tags as spaces (ph, t).

defaultFields boolean

Return with decoration results default set of fields. For source term: Concept oid, Concept id4, Term oid, Term id4, Term name. For target term, Definition, Concept oid, Concept id4, Dictionary, Section, Domain, all concept level fields, Term oid, Term id4, Term name, Language, Region, Term modification date, Term modification author, all term level fields.

sourceFields string[]

When defaultFields is set to false you may specify what fields to include for source term.
An array of Field oids. TermWeb always sends next fields: Concept oid, Term oid, Term name.

targetFields string[]

When defaultFields is set to false you may specify what fields to include for target term.
An array of Field oids. TermWeb always sends next fields: Concept oid, Term oid, Term name and Language.
• Get default configuration for API Templates

GET /api/v4/api-templates/defaults

Description

Returns default configuration for API templates used by TermWeb server.

Request documentation
Request parameters

No parameters
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APITemplateSettings

JSON object of APITemplateSettings.
• Find

GET /api/v4/api-templates/

Description

Finds API template with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter API template objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters API template with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters API template with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for API template objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content APITemplate[]

Found API template of type APITemplate.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/api-templates/rownum/{id}

Description

Finds rownumber of API template with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

API Template id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter API template objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters API template with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters API template with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for API template objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/api-templates/{id}

Description

Looks for API template with specified id.

Request documentation

Path parameters

id number

API Template id to look for

format enum

<optional>, default is 'FULL'
Response format for API template objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body APITemplate

JSON object of API Template.
• Create

POST /api/v4/api-templates/

Description

Creates new API template from JSON data sent in payload.

Request documentation

Payload

body APITemplate

JSON object of type APITemplate.

format enum

<optional>, default is 'FULL'
Response format for API template objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APITemplate

Created object of API template.
• Update

PUT /api/v4/api-templates/{id}

Description

Updates existing API template from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of API Template which need to be updated

Payload

body APITemplate

JSON object of type APITemplate. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for API template objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APITemplate

Updated API template object.
• Partial update

PUT /api/v4/api-templates/partial/{id}

Description

It updates only specified parts of API template from JSON data sent in payload. Unlike method PUT /api/v4/api-templates/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of API Template which need to be updated

Payload

body APITemplate

JSON object of type APITemplate. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for API template objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body APITemplate

Patched API template object.
• Delete

DELETE /api/v4/api-templates/{id}

Description

Deletes API template with specified id.

Request documentation

Path parameters

id number

API Template id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/api-templates/async/{id[]}

Description

Deletes API template with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

API Template ids of API template to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is API template id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.2.4. Job tasks endpoint

Description

Endpoint provides information about asynchronous tasks launched by current user.

• JobTask DTO
Object attribute Description

jobId number

Job object id to which this task is related. Internal use only.

ordinal number

Serial number of this task in job. Internal use only. Internal use only.

parentTaskId number

Job task parent id. Tasks can launch subtasks. Internal use only.

launchedAt number

Launch date and time in milliseconds since Unix Epoch.

launchedBy number

User id launched this job.

launchedByLocale number

Locale used by user during launch of job.

finishedAt number

Finish date and time in milliseconds since Unix Epoch

stoppedBy number

User id which stopped this job. Filled only when job has been interrupted.

processed number

Number of processed objects by this task.

processedSuccessfully LangMapping[]

Number of successfully processed objects without failures by this task.

total GroupMapping[]

Total amount of objects to process by this task.

status enum

Job task status. Possible values are CREATED, RUNNING, PAUSED, HALTED, FAILURE, STOPPED, FINISHED, TERMINATED. See Job Task Statuses.

id number

Job task id.

version number

Job task version number. Represents latest modification counter.
JobTaskStatus
Status Description

CREATED string

JobTask has been created for execution. Params are stored in DB.

RUNNING string

JobTask is executed by one of the ExecutorService. In case of crash job can stuck in that status.

PAUSED string

JobTask has been paused by user call.

HALTED string

JobTask has been halted by system call (e.g. shutdown). TermWeb will restore halted tasks on next run.

FAILURE string

During execution of code in JobTask something went wrong. Execution has been stopped.

STOPPED string

JobTask has been stopped by user call.

FINISHED string

JobTask has been successfully completed.

TERMINATED string

JobTask execution has been interrupted by another JobTask (e.g. sequential update of Dictionary ES index).
JobTaskResult DTO
Object attribute Description

jobId number

Job object id to which this task is related to. Internal use only.

jobTaskId number

Job task id to which this results related to.

parentJobTaskId number

Job task parent id. Tasks can launch subtasks. Internal use only.

createdAt number

Launch date and time in milliseconds since Unix Epoch.

results Map<string,Object>

User id launched this job.

id number

Job task id.

version number

Job task version number. Represents latest modification counter.
• Active

GET /api/v4/jobtasks/active

Description

Looks for running asynchronous tasks launched by current user.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body JobTask[]

An array of found job tasks.
• Status

GET /api/v4/jobtasks/status/{id}

Description

Looks for status of job task with specified id.

Request documentation

Path parameters

id number

Job task id to look for
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body JobTask

JSON object of Job task.
• Results

GET /api/v4/jobtasks/results/{id}

Description

Looks for results of job task with specified id.
Internal use only.

Request documentation

Path parameters

id number

Job task id to look for
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body JobTaskResult[]

An array JSON objects of type Job Task Result.

13.2.5. License endpoint

The endpoint provides two methods to view license and to update it.

• License DTO
Object attribute Description

validLicense boolean

true when license is valid. false will be returned when license has expired or user entered invalid or expired license text in update method.

owner string

Name of owner for that license, like Big Company Name

expireDate number

Expiration date and time in milliseconds since Unix Epoch until license is valid.

clients number

Number of clients which can be created in this installation by using this license. 0 means "Unlimited"

guestAccount boolean

true when this installation allows to use guest account.

maxAccounts number

Maximum number of named users. 0 means "Unlimited"

maxConcurrentUsers number

Maximum number of users which can use system concurrently (including guest users).

maxConcurrentGuests number

Maximum number of guest users which can use system concurrently.

xmlRpcApi boolean

true when TermWeb can provide XML-RPC API.

soapApi boolean

true when TermWeb can provide SOAP webservices API.

ldapSupport boolean

true when TermWeb can authenticate users via LDAP.

samlSupport boolean

true when TermWeb support SSO authentication with SAML2.0 support.

bima boolean

true when Business Integration Message Adapter is allowed for use.

availableUserSlots number

Left number of users for current license which can be created in the system.
• Get license information

GET /api/v4/system/license

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body License

JSON object of License.
• Update license

POST /api/v4/system/license

Request documentation
Payload

body string

license text
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body License

JSON object of License.

Http status

200 OK

License is valid and successfully applied

400 Bad request

License is invalid or expired.

13.2.6. Features endpoint

This endpoint provides methods with information about what is enabled and what settings in current TermWeb installation.
Mostly in use by TermWeb UI client.
Unauthorized access allowed here.

GET /api/v4/system/features or GET /api/v4/system/features/client/{clientLogin}

Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload attributes

DEVELOPMENT boolean

true when current installation is running in development mode.

SESSION_TIMEOUT number

Server setting for how long authentication token will be valid. Value in seconds.

MULTIPLE_CLIENT boolean

true when installation is multitenant.

GUEST_AUTO_DISABLED boolean

true when login is enabled for anonymous guests.

MULTIVALUED_SEPARATOR string

Separator for multivalued picklists.

ALWAYS_WILDCARD boolean

Default search mode for input string. When true search results will always do substring search.

MAX_FILE_SIZE number

Maximum file size accepted by TermWeb in POST /api/v4/files/upload. Size in bytes.

FEEDBACK_MAX_FILE_SIZE number

Maximum file size accepted by TermWeb in POST /api/v4/feedback. Size in bytes.

VERSION string

Version of running TermWeb.

BUILD_DATETIME number

Date when build has been made of running TermWeb.

GUEST_TOKEN TokenInfo

In case when guest login activated for current client (default client or client specified in path parameter clientLogin) features response will have valid TokenInfo for guest access.

13.2.7. Features script endpoint

This method wraps response object of GET /api/v4/system/features into script file. This script file creates in Window object property with name termwebFeatures which contains all system features including GUEST_TOKEN. To determine client login server is using http header Referer when it equals to termweb.properties base.url property, like ${base.url}/client/{clientLogin} it will look for automatic guest login settings.

Response documentation
Headers

Content-Type

text/javascript; charset=UTF-8

Payload

Body script

 
(function initTermWeb4Features() {
  window.termwebFeatures = JSON.parse('{"DEVELOPMENT":false, ...}');
})();

13.2.8. Statistics endpoint

Description

Endpoint provides information about TermWeb’s usage

• Statistics DTO
Object attribute Description

startTime number

Server start date and time in milliseconds since Unix Epoch

onlineUsers OnlineUser[]

An array with information about current online users. See OnlineUser.

totalSummary SummaryDto

Full statistics about use of TermWeb since installation. See StatisticsSummary.

currentMonthSummary MonthSummaryDto

Current month statistics about use of TermWeb. See StatisticsMonthSummary.

currentMonthDetails MonthDetailsDto

Current month detailed statistics about use of TermWeb. See StatisticsMonthDetails.
• OnlineUser DTO
Object attribute Description

userLogin string

User username

userId number

User id

clientLogin string

User’s Client loginName

loginTime number

User’s login date and time in milliseconds since Unix Epoch

lastUsageTime number

Last date and time when user interacted with TermWeb in milliseconds since Unix Epoch

ipAddress string

An IP address from which user logged in

partId string

4 last symbols of server session id. Helps to identify several concurrent sessions of same user.

apiLogin boolean

true if user logged in via XML-RPC or SOAP endpoints

apiRequests boolean

Amount of XML-RPC or SOAP requests made
• StatisticsSummary DTO
Object attribute Description

visits number

Total amount of visits

users number

Total amount of unique users been working with this installation

apiUsers number

Total amount of unique API users been working with this installation

apiRequests number

Total amount of API requests made by users working through XML-RPC and SOAP services

totalTime string

Human-readable string containing combined usage time of all user logins

installDate number

Server installation date and time in milliseconds since Unix Epoch
• StatisticsMonthSummary DTO
Object attribute Description

month number

Month number to which this statistics belongs. 1 for January, 12 - December

year number

Year to which this statistics belongs

visits number

Amount of visits for this month

users number

Amount of unique users been working this month

apiVisits number

Amount of API visits for this month

apiRequests number

Amount of API requests made by users working through XML-RPC and SOAP services

totalTime string

Human-readable string containing combined usage time of all user logins this month

averageVisits string

Human-readable string average user visits per day

averageApiVisits string

Human-readable string average user API visits per day

averageApiRequests string

Human-readable string average amount of API requests per day

averageTime string

Human-readable string containing average use per day this month
• StatisticsMonthDetails DTO
Object attribute Description

onlineUsers UserLogItem[]

List of all user logins for one month. See UserLogItem.
• UserLogItem DTO
Object attribute Description

userLogin string

User username

userId number

User id

clientLogin string

User’s Client loginName

loginTime number

User’s login date and time in milliseconds since Unix Epoch

logoutTime number

User’s logout date and time in milliseconds since Unix Epoch

ipAddress string

An IP address from which user logged in

apiLogin boolean

true if user logged in via XML-RPC or SOAP endpoints

apiRequests boolean

Amount of XML-RPC or SOAP requests made by user
• Statistics

GET /api/v4/system/statistics

Description

Returns overall usage statistics for current installation.

Request documentation

Request parameters

all-clients

<optional> Show information for all clients. Available only to system administrators
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body StatisticsSummary

A JSON response of type StatisticsSummary.
• Month Statistics

GET /api/v4/system/statistics/{year}/{month}

Description

Returns monthly usage statistics for current installation.

Request documentation

Path parameters

year

Year for which looking usage statistics

month

Month for which looking usage statistics

Request parameters

all-clients

<optional> Show information for all clients. Available only to system administrators
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body StatisticsSummary

A JSON response of type StatisticsMonthSummary.
• Online users

GET /api/v4/system/statistics/online-users

Description

Returns list of users currently online.

Request documentation
Request parameters

all-clients

<optional> Show information for all clients. Available only to system administrators
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body OnlineUser[]

A JSON response of array with elements of type OnlineUser.

13.3. Users administration

13.3.1. Users endpoint

Description

Edit user component:

Only system administrators can edit clients section for users (clients section for sysadmins is not available because sysadmin always can login to any client).

System administrator can’t edit their own set of clients or roles.

Client administrator can’t edit their own set of roles.

Client administrator can’t assign 'System administrator role'.

Client administrator can’t change System administrator users.

Normal users should not be able to edit or create users at all. An exception are normal API users that should be able to update at least their own object (password, fullname, email).

In the interface for new users there should be an option 'send password reset link in email'. In the case that password fields should remain unknown, server should send email with reset link after successfully saving changes.

When editing existing user should present checkbox 'User must change password at next logon' (even for current, just for case when two administrators sharing account).

Password requirement is configured on server side and should be validated by UI client and by server. (Server should provide api method for password strength setting, see System → Administrator Tools → Password strength)

Users list:

Filtering by name should work on two fields: username and full name.

User must be able to sort list by username, fullname, user roles, status, created/modified dates.

List should include external users from other clients as well.

Guest users should not be visible in the list.

System administrator should be able to assign client to multiple users from list.

Client or system administrator should be able to delete multiple or single users from list.

User should not be able to delete himself.

System or client administrator should not be able to delete last client administrator.

Client administrator should not be able to delete any system administrator

Users with role 'Edit users' should be able to edit users, but not delete or create.

DevNote:

don’t allow modification of user type through api.

for expireDate server is waiting format 'YYYY-MM-DD'

to get password settings from server use /users/password-settings

to assign multiple clients for multiple users use PUT /users/clients and dto AssignClientRequest.

To summarise what users can do. User edit component: Self edit for every type of user:

full name

username

email

password

change password at next logon System administrator:

full name

username

email

password

expires on

active status

change password at next logon

clients

roles (all roles accessible) Client administrator cannot edit System administrator Client administrator can edit next properties for client admins and regular users

full name

username

email

password

expires on

active status

change password at next logon

roles (Administrator, User editor, dictionary admin) User editor cannot edit Client administrators or System administrators User editor:

full name

username

email

password

expires on

active status

change password at next logon

User list actions:

User cannot delete himself or change clients for himself

System administrator can change other users clients

Client administrator can’t delete system administrators or change their clients

User editor cannot create or delete users

User editor cannot export or import users

• User DTO
Object attribute Description

username string

Unique username per client of user used as login. May contain only Latin letters and numbers.

fullName string

Full name of user.

email string

User email.

title string

User’s title.

expDate number

Expiration date and time in milliseconds since Unix Epoch when user be deactivated.

type enum

User type. Usually you cannot specify it on creation or update.
Internal use mostly.
Possible values are: NORMAL, GUEST, GUEST_AUTOLOGIN, GUEST_CLIENT_AUTOLOGIN, EXTSYSADMIN, LEGACY, ROLEBASED.

active boolean

Status of user. When false user cannot access TermWeb.

password string

[Edit format] provide new value when you need to change password. Otherwise, send this string: ****** to keep password unchanged.
Password must fulfill validation password, otherwise server will reject new value, see Password settings.

confirmPassword string

[Edit format] provide new value when you need to change password. Otherwise, send this string: ****** to keep password unchanged.
Password must fulfill validation password, otherwise server will reject new value, see Password settings.

roles string[]

[Edit format] Role system names assigned to this user. See User roles.

clientIds number[]

[Edit format] List client ids to which user is mapped to.

groups Group[]

[Edit format] An array of Group objects to which user belongs to.

sendNotificationEmail true

[Edit format] Set to true when user need to reset password. User will receive reset link via email.

forcePasswordChange boolean

[Edit format] Set to true when user must change it on next login.
Visible to user which forced to change password.

lastLogins UserLogItemDto[]

[Edit format] List of 10 last user logins, available only to admins and user editors.

originType enum

User’s origin type. Internal use mostly.
Possible values are: TERMWEB, OPENID, OIDC, SAML, LDAP, API.

origin boolean

Url of user source

clientId number

Client id to which object belongs

id number

User id.

oid string

User oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Import users and groups

POST /api/v4/users/import

Description

Imports users and groups from compatible XML file with specified settings.

Request documentation

Headers

Content-Type

multipart/form-data

Payload fields

file (binary)

Multipart data containing file contents.

fileName string

Name of uploaded file

overwrite-user boolean

<optional>, default is false, set to true when you want to override existing users with same username.
When false TermWeb will create new user with name having index in the end, like 'username_1'.

overwrite-group boolean

<optional>, default is false, set to true when you want to override existing groups with same name.
When false TermWeb will create new group with name having index in the end, like 'Group name _1'.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload UserImportResult

userCount number

Number of user created with import.

groupCount number

Number of groups created with import.
• Export users and groups

GET /api/v4/users/export

Description

Returns all users with password hashes and groups, and their mappings in XML file.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/xml

Content-Disposition

attachment; filename="some_file_name"

Content-Length

Generated file length

Payload

body

XML file containing
• Assign clients

PUT /api/v4/users/assign-clients/

Description

Updates client mapping for specified users in request.
Any previous existing mappings will be removed with completion of that operation.

Request documentation

Headers

Content-Type

application/json

X-Auth-Token

Unexpired authentication token

Payload fields

users number[]

An array of users ids to update their client mappings.

clients number[]

An array of clients ids to which users must me mapped.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

number of successfully updated users
• Password settings

GET /api/v4/users/password-settings

Description

Returns password settings for this TermWeb installation.
These settings are configured by system administrator in Admin view → System → Administrator tools → Password strength.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload fields

regExp string

String containing regular expression for password validation.

msg string

String message for user when password is not matching to regular expression.
• GuestSettings DTO
Object attribute Description

enabled boolean

true when guest user authentication is enabled.

username string

Login name for guest user.

password string

Password for guest user.
Password must fulfill validation password, otherwise server will reject new value, see Password settings.

loginMethod enum

Setting which configures how guests will login into TermWeb. Possible values are: NORMAL, GUEST_AUTOLOGIN, GUEST_CLIENT_AUTOLOGIN.

autoAlwaysDisabled boolean

true when login method GUEST_AUTOLOGIN is not available for current client (only Default Client can have this setting).

enableQuickFilters boolean

true when guests can user quick filters. Quick filters created by guests will be temporary and deleted after logout.

enableSearchModes boolean

true when guests can modify search settings in Search View (can select Filters, Domains and multi-field search).

enableCommenting boolean

true when guests can leave comments on Concepts.
• Get guest settings

GET /api/v4/users/guest

Description

Returns guest settings for current client of authentication token.

Guests page should repeat functionality of old one. Here are the major functions:

  • guest login can be enabled or disabled

  • guest password should be validated as any other password in the system. Except one thing - it should be visible as regular text field.

  • guest login can be changed to other value, user name should be unique for current client.

  • login method one of three possible values (Automatic (always), Automatic (client), Normal

  • "Automatic (always)" should be visible and can be enabled only for default client (Admin).

loginMethod value mapping:

  • UserType.GUEST_AUTOLOGIN – Automatic (Always)

  • UserType.GUEST_CLIENT_AUTOLOGIN – Automatic (when client is specified in URL)

  • UserType.NORMAL – Normal

to disable selection of "Automatic (always)" check the property in GuestSettings.autoAlwaysDisabled

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body GuestSettings

JSON object of GuestSettings.
• Update guest settings

PUT /api/v4/users/guest

Description

Updates guest settings for current client of authentication token.
See Get guest settings for description.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Payload

body GuestSettings

Updates for Guest settings in JSON object of GuestSettings.
Response documentation

Status

code number

200 OK in case of successful update.
• Find

GET /api/v4/users/

Description

Finds users with specified query parameters available to current user.

Request documentation

Query parameters

login string

<optional>, default is null
Synonym for username attribute.
Filters users with username name starting with provided value. Search will be case insensitive.

full-name string

<optional>, default is null
Filters users with full name starting with provided value ignoring case.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters users with username starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters users with username equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content User[]

Found users of type User.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/users/rownum/{id}

Description

Finds rownumber of user with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

User id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

login string

<optional>, default is null
Synonym for username attribute.
Filters users with username name starting with provided value. Search will be case insensitive.

full-name string

<optional>, default is null
Filters users with full name starting with provided value ignoring case.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters users with username starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters users with username equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/users/{id}

Description

Looks for user with specified id.

Request documentation

Path parameters

id number

User id to look for

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body User

JSON object of User.
• Create

POST /api/v4/users/

Description

Creates new user from JSON data sent in payload.

Request documentation

Payload

body User

JSON object of type User.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body User

Created object of user.
• Update

PUT /api/v4/users/{id}

Description

Updates existing user from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of User which need to be updated

Payload

body User

JSON object of type User. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body User

Updated user object.
• Partial update

PUT /api/v4/users/partial/{id}

Description

It updates only specified parts of user from JSON data sent in payload. Unlike method PUT /api/v4/users/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of User which need to be updated

Payload

body User

JSON object of type User. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for user objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body User

Patched user object.
• Delete

DELETE /api/v4/users/{id}

Description

Deletes user with specified id.

Request documentation

Path parameters

id number

User id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/users/async/{id[]}

Description

Deletes users with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

User ids of users to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is user id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.3.2. Groups endpoint

Description

If necessary, you can add a new user group. User groups are used for limiting or giving access to parts of a dictionary, API access. Also, user groups can have custom session timeout.

Group members are specified via partial update method PUT /api/v4/groups/partial/{id}. Which members are to receive access to which sections of dictionaries is set by using Permission Schemes, defining a set of rights for the user groups and then assigning this permission scheme to the desired dictionary or section).

TermWeb comes with two system groups which is not possible to delete, but you may change names and description:

  • All users – Group containing all named users in Client, except guest users.

  • Guests – Group representing guest users (anonymous users) working with TermWeb without personal account. Guest users can be enabled via PUT /api/v4/users/guest/.

• Group DTO
Object attribute Description

name string

Unique name per client of group.

description string

Text describing that group.

timeout number

Session timeout setting for users of this Group.

pwdChange number

Number of days till the next password change for users of this Group.

viewsMap Map<number,Set<number>

A map containing assigned Views to Dictionary. One dictionary can have multiple assigned views. Map structure is: Map<dictionary_id, Set<view_id>>.

filterMap Map<number,number>

A map containing Filter applied to search results from <<doc-dto-dictionary,Dictionary> for users of that Group}.

type enum

A group type. System attribute. Can’t be changed via API. Possible values are: NORMAL, ALL_USERS, GUEST. Default value is: NORMAL. ALL_USERS and GUEST is created by TermWeb automatically.

Groups of type GUEST always don’t have access to API.

langCode3 string

When group is Language Group, this value will have three-letter code from ISO 639.

hasApiAccess boolean

true when members of that group can have API access.

currentUsersNumber number

[Edit format] Number of group members.

groupMembers User[]

[Edit format] An array of Users in short format assigned to that group.

clientId number

Client id to which object belongs

id number

Group id.

oid string

Group oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Find

GET /api/v4/groups/

Description

Finds groups with specified query parameters available to current user.

Request documentation

Query parameters

include-all boolean

<optional>, default is true
Includes "All users" group to search results.

include-guest boolean

<optional>, default is true
Includes "Guests" group to search results.

include-private boolean

<optional>, default is false
Includes "Owner" group to search results (used mostly in visibility settings).

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters groups with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters groups with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Group[]

Found groups of type Group.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/groups/rownum/{id}

Description

Finds rownumber of group with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Group id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

include-all boolean

<optional>, default is true
Includes "All users" group to search results.

include-guest boolean

<optional>, default is true
Includes "Guests" group to search results.

include-private boolean

<optional>, default is false
Includes "Owner" group to search results (used mostly in visibility settings).

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters groups with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters groups with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/groups/{id}

Description

Looks for group with specified id.

Request documentation

Path parameters

id number

Group id to look for

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Group

JSON object of Group.
• Create

POST /api/v4/groups/

Description

Creates new group from JSON data sent in payload.

Request documentation

Payload

body Group

JSON object of type Group.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Group

Created object of group.
• Update

PUT /api/v4/groups/{id}

Description

Updates existing group from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Group which need to be updated

Payload

body Group

JSON object of type Group. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Group

Updated group object.
• Partial update

PUT /api/v4/groups/partial/{id}

Description

It updates only specified parts of group from JSON data sent in payload. Unlike method PUT /api/v4/groups/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Group which need to be updated

Payload

body Group

JSON object of type Group. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for group objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Group

Patched group object.
• Delete

DELETE /api/v4/groups/{id}

Description

Deletes group with specified id.

Request documentation

Path parameters

id number

Group id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/groups/async/{id[]}

Description

Deletes groups with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Group ids of groups to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is group id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.3.3. Role endpoint

• Role DTO
Object attribute Description

name string

Descriptive name of role

systemname enum

System name of a role. It can be one of the next possible values are: ADMIN, SYSADMIN, USEREDITOR or one
special value starting with DICTIONARY_ADMIN@ plus Dictionary oid.
• Ger roles for user

GET /api/v4/roles

Description

Finds all roles available for current user. It will return only roles for current Client of user.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Role[]

An array of assigned user roles of type Role
• Ger roles for client

GET /api/v4/roles/find-roles-for-client

Description

Finds all roles for specified client. Token should be valid for specified client.

Request documentation

Headers

X-Auth-Token

Unexpired authentication token

Request parameters

client-id

Client id to look for
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Role[]

An array of used roles in a Client of type Role

13.4. Permissions administration

13.4.1. Access rules endpoint

This endpoint provides information about user permissions

• DictionaryPermissions
Object attribute Description

dictionaryId number

Dictionary id to which this set of permissions related.

permissions Map<DictionaryPermission,boolean>

Map of top-level permissions for dictionary. When users have permission to work with any dictionary section, this value will be true.
Keys is one of values from enum Dictionary permissions.

sectionPermissions Map<number,Map<DictionaryPermission,boolean>>

Permissions related to specific section in dictionary. Parent map will have Section id as key, and value will be a map with permissions. Nested map will have only permissions with suffix 'CONCEPT_'.

sectionOidPermissions Map<string,Map<DictionaryPermission,boolean>>

Same as sectionPermissions except the key in parent map will be Section oid.
• Dictionary permissions enum
Value Description

DICT_READ string

User can read dictionary metadata and concepts with terms from it.

DICT_UPDATE string

User can update dictionary metadata.

DICT_DELETE string

User able to delete dictionary.

CONCEPT_CREATE string

User can create a new concept, and restore deleted concepts from history

CONCEPT_PRINT string

User can print concepts.

CONCEPT_IMPORT string

User can import concepts.

CONCEPT_EXPORT string

User can export concepts.
• Get dictionary permissions

GET /api/v4/access/dictionary-permissions

Returns dictionary permissions for current user

Request documentation

Query parameters

dictionary_id number[]

An array of dictionary ids for which we’re retrieving permissions information.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DictionaryPermissions[]

A json array of elements of type DictionaryPermissions for every requested dictionary

13.4.2. Permission schemes endpoint

Description

Permission schemes is used to restrict or give access to different dictionaries and sections.

Please note this endpoint is subject to change in the future.

• Permission Scheme DTO
Object attribute Description

name string

Domain name.

description string

Domain description.

TBD number

TBD

clientId number

Client id to which object belongs

id number

Permission scheme id.

oid string

Permission scheme oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Find by client

GET /api/v4/permissionschemes/find-permissionschemes-by-client

Description

Finds permission schemes for specified client.

Request documentation

Query parameters

client_id number

Client id to look for
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body PermissionScheme[]

An array of found permission schemes of type Permission scheme.

13.5. Dictionaries administration

13.5.1. Dictionaries endpoint

Description

Dictionary is terms data definition.

It defines languages used for terms and metadata stored with terms.

Terms of same meaning can be grouped into a Concept and mostly is. Concept consists of synonyms of term in same language and translations in other languages.

Languages

  • Using ISO 639-2 three-letter codes by default (eng - English, swe - Swedish, etc). You may specify custom language code, but this code must not be the same as real language code or geographical/orthographical variant.

  • For all languages you may customise writing direction (LTR or RTL). By default, TermWeb is using common writing directions for languages (like LTR for English, RTL for Arabic).

  • For each language you may specify geographical variant, e.g.: US - United States, UK - Great Britain, CA - Canada, AU - Australia, etc, or any other existing country you may wish. For special cases you may create custom region.

  • For each language you may specify orthographical variant to mark specific writing script of term. For example for Japanese you can choose scripts Hiragana (hira), Katakana (kana) or even combined Hiragana + Katakana (hrkt).

Metadata

You may use predefined fields (TBX-Default based) or custom fields for Concept or Term.

Custom fields can be created for Concept or Term level, here you may find description of supported data types:

Table 1. Custom fields
Type Description

Singleline

Text, will be presented as single line text input. Max symbol length is 16 383 (216-1).

Multiline

Text, will be presented as multi line text input. Max symbol length is 16 383 (216-1).

Date

Date, input will accept only valid date values without time.

Picklist

List of predefined values to be selected. User may select only one value.

Multivalued

List of predefined values to be selected. User may select multiple values.

Incremental

Number value, TermWeb will generate new incremented number after last used value. E.g. when we have field with value 500, TermWeb create automatically number 501 for new Term or Concept.
For all field types is possible

To specify that field is required. User won’t be able to save Concept or Term without providing value to that field (including predefined fields).

For all text fields (including predefined) you may specify:

  1. Encoding (Unicode or Latin letters with numbers only).

  2. Regular expression, TermWeb will validate input to be matching that expression.

  3. Number presentation, will accept only valid integer numbers (range of valid numbers is from -231 to 231-1).

  4. Minimal and maximum length limit. Max limit can’t be bigger than 216-1.

Table 2. Concept predefined fields
Type TBX name Description

Concept origin

conceptOrigin

Customer subset

customerSubset

Definition

definition

Environment subset

environmentSubset

Example

example

Explanation

explanation

Product subset

productSubset

Project subset

projectSubset

Source

source
Table 3. Term predefined fields
Type TBX name Description

Animacy

animacy

Context

context

Customer subset

customerSubset

Definition

definition

Environment subset

environmentSubset

Example

example

Grammatical gender

grammaticalGender

Grammatical number

grammaticalNumber

Picklist: singular, plural, dual, mass, or otherNumber

Part of speech

partOfSpeech

Process status

processStatus

Product subset

productSubset

Project subset

projectSubset

Sample sentence

sampleSentence

Source

source

Source language

sourceLanguage

Term location

termLocation

Term type

termType

Usage note

usageNote

Usage status

administrativeStatus

For every predefined field is possible to change standard name. For standard TBX values of picklists is possible to change names too.

• Dictionary DTO
Object attribute Description

name string

Dictionary name.

description string

Description of dictionary.

sections Section[]

List of Dictionary sections of type Section available for reading by current user.

allSections Section[]

List of all Dictionary sections of type Section created in Dictionary.

languages Language[]

List of Dictionary languages of type Language.

conceptFields Field[]

List of Dictionary concept fields of type Field.

termFields Field[]

List of Dictionary term fields of type Field.

emailRecipientId number

User id of email recipient.

sortIndex number

Order number for displaying in user specified order.

hasDomains boolean

true when domains has at least one Domain linked to this dictionary

domainPresentation enum

Setting how to represent selected domains for Concept in a concept view. Default value is HORIZONTAL.
Possible values are:
FLAT every selected Domain will be printed on separate lane with full path to it
HIERARCHICAL show all selected domains ordered list
HORIZONTAL everything is represented in one line, separated by square bullets, domains on a same level and parent are grouped.

concepts number

Number of non-deleted concepts in a dictionary.

clientId number

Client id to which object belongs

id number

Dictionary id.

oid string

Dictionary oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Section DTO
Object attribute Description

name string

Section name.

viewId number

View id which assigned to section.

numberOfConcepts number

Number of concepts created in this section

deletable boolean

true when section can be deleted.

sortIndex number

Order number for displaying in user specified order

dictionaryId number

Dictionary id to which section related.

clientId number

Client id to which object belongs

id number

Section id.

oid string

Section oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Language DTO
Object attribute Description

name string

Language name.

dictionaryId number

Dictionary id in which that language has been created.

clientId number

Client id in which that language has been created.

code string

The ISO639-2 code (3 chars) in case of standard code. In case of custom language can contain anything but always starts with 3 chars from ISO639-2 codes list.

code2 string

The ISO639-1 code (2 chars) to be used for Locale creation, e.g sv, en, pt, de. Can be empty string.

code3 string

The ISO639-2 code (3 chars) in case of standard code e.g. swe, eng, por, deu, haw. In case of custom language can contain anything.

isIso boolean

Flag which indicates if this language is defined in ISO639-2.

sortIndex number

Order number for displaying in user specified order

variants LanguageVariant[]

List of geographical and orthographical variants of type Language Variant.

rtl boolean

true when language has Right-to-left writing direction of script.

id number

Language id.

oid string

Language oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.
• Language Variant DTO
Object attribute Description

type number

0 for Geographical, 1 for Orthographical

code string

Variant code string

predefined boolean

true when code of this value from list of TermWeb predefined values

languageId number

Language id to which this variant belongs to.

name string

Language variant name.

sortIndex number

Order number for displaying in user specified order

id number

Language variant id.

oid string

Language variant oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.
• Field DTO
Object attribute Description

name string

Field name.

specifiedName string

The user specified name of the field if any.

dictionaryId number

Dictionary id to which this field belongs.

dataCategory enum

GENERIC in case of custom field.
In case of TBX compatible field, values are: DEFINITION, EXAMPLE, GRAMMATICAL_GENDER, GRAMMATICAL_NUMBER, PROCESS_STATUS, SOURCE, SOURCE_LANGUAGE, USAGE_NOTE, CONTEXT, USAGE_STATUS, TERM_TYPE, CONCEPT_ORIGIN, CUSTOMER_SUBSET, ENVIRONMENT_SUBSET, EXPLANATION, PRODUCT_SUBSET, PROJECT_SUBSET, ANIMACY, PART_OF_SPEECH, SAMPLE_SENTENCE, TERM_LOCATION.
In case of system type field, values are: DOM - concepts domain,
DICT - dictionary,
SECT - dictionary sections,
SUBC - subclass, not in use,
CONID - Concept ID (serial number in dictionary),
CREBY - concept created by,
CREDATE - concept creation date,
CHGBY - last author of concept changes,
CHGDATE - concept last modification date,

TERM - term name,
LANG - term language,
GVAR - geographical variant,
OVAR - orthographical variant,
TERM_CONFIG - internal use only,
TCREBY - term created by,
TCREDATE - term creation date,
TCHGBY - term last author of term changes,
TCHGDATE - term last modification date,
TERM_ID - Term ID (serial number in dictionary) .

fieldType enum

Type of field. Possible values are: SINGLELINE, MULTILINE, NUMBER, PICKLIST, MULTISELECT, DATE, CHECKBOX, USER.

level enum

Level of field. Possible values are: CONCEPT, TERM.

model FieldModel

Settings of field. Object of type Field Model.

sortIndex number

Order number for displaying in user specified order

id number

Field id.

oid string

Field oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Field Model DTO
Object attribute Description

required boolean

true when field value can’t be empty.

minLen number

The minimum length for the field value. 0 for no limit.

maxLen number

The maximum length for the field value. 0 for no limit.

regExp string

A regular expression describing the allowed values in the field.

number boolean

true when field value can have only numbers.

unicode boolean

true when field value can contain any string, otherwise only latin character set.

picklistItems PickListItem[]

Picklist items when field type is Picklist or Multiselect. Object of type Picklist item.

id number

Field model id.

oid string

Field model oid. This is object id from old objects.
• Picklist Item DTO
Object attribute Description

name string

An item display name specified by user

tbxName string

A standard TBX name for picklist item. Must be used unless user specified custom in name attribute.

sortIndex number

Order number for displaying in user specified order

fieldOid string[]

Field oid to which this item is related.

id number

Picklist item id.

oid string

Picklist item oid. This is object id from old objects.
• TBX DataCategory
Object attribute Description

key string

localizable name key of the data category. Internal use only.

name string

localizable name key of the data category.

id string

ISO id for the category, e.g. 08 for ISO12620A-08

fieldType enum

Type of field. Possible values are: SINGLELINE, MULTILINE, NUMBER, PICKLIST, MULTISELECT, DATE, CHECKBOX.

picklistItems string[]

List of possible values for picklists fields.

levels string[]

An array of field levels where this category can be used. Possible values are: 'CONCEPT', 'TERM'.
• Data categories

GET /api/v4/dictionaries/data-categories

Description

Returns list of supported TBX data categories by this TermWeb installation

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DataCategory[]

Array of available TBX data categories of type DataCategory.
• Language replace

POST /api/v4/dictionaries/language-replace/

Description

This operation moves terms of dictionary from one language to another one.
This operation may run asynchronous when transfer takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Query parameters

dictionary-id number

Dictionary id where to apply language replace operation.

from-id string

Language variant code in custom format: <lang_var>[;[region_code];[script_code]]

to-id string

Language variant code in custom format: <lang_var>[;[region_code][;script_code]]
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful transfer or 204 Accepted when operation is still transferring.

Payload attributes InvocationResult

result number

Number of moved terms.

jobTaskId number

When operation went to asynchronous transfer, this value will have id of running job task. See JobTask.
• Find

GET /api/v4/dictionaries/

Description

Finds dictionaries with specified query parameters available to current user.

Request documentation

Query parameters

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters dictionaries with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters dictionaries with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for dictionary objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Dictionary[]

Found dictionaries of type Dictionary.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/dictionaries/rownum/{id}

Description

Finds rownumber of dictionary with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Dictionary id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters dictionaries with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters dictionaries with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for dictionary objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/dictionaries/{id}

Description

Looks for dictionary with specified id.

Request documentation

Path parameters

id number

Dictionary id to look for

format enum

<optional>, default is 'FULL'
Response format for dictionary objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Dictionary

JSON object of Dictionary.

13.5.2. Sections endpoint

Description

Sections allows to split up dictionary content by named section. Each section can have different set of permissions and displayed attributes. When Dictionary is created it will have one section with same name as dictionary, this name can be changed to anything else. When section is last, it cannot be deleted from dictionary.

• Clear

POST /api/v4/sections/clear/

Description

Clears Dictionary sections, by removing every concept from there.
Changes won’t be stored in dictionary history.

Request documentation

Query parameters

section-id number[]

An array of sections ids to clear.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful clearance or 204 Accepted when operation is still clearing.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is section id and value is boolean flag indicating result of clearance.

jobTaskId number

When operation went to asynchronous clearing, this value will have id of running job task. See JobTask.
• Find

GET /api/v4/sections/

Description

Finds sections with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter section objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters sections with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters sections with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Section[]

Found sections of type Section.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/sections/rownum/{id}

Description

Finds rownumber of section with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Section id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter section objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters sections with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters sections with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/sections/{id}

Description

Looks for section with specified id.

Request documentation

Path parameters

id number

Section id to look for

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Section

JSON object of Section.
• Create

POST /api/v4/sections/

Description

Creates new section from JSON data sent in payload.

Request documentation

Payload

body Section

JSON object of type Section.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Section

Created object of section.
• Update

PUT /api/v4/sections/{id}

Description

Updates existing section from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Section which need to be updated

Payload

body Section

JSON object of type Section. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Section

Updated section object.
• Partial update

PUT /api/v4/sections/partial/{id}

Description

It updates only specified parts of section from JSON data sent in payload. Unlike method PUT /api/v4/sections/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Section which need to be updated

Payload

body Section

JSON object of type Section. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for section objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Section

Patched section object.
• Delete

DELETE /api/v4/sections/{id}

Description

Deletes section with specified id.

Request documentation

Path parameters

id number

Section id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/sections/async/{id[]}

Description

Deletes sections with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Section ids of sections to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is section id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.5.3. Fields endpoint

Description

Fields for Dictionary. Fields describes what kind of attributes terms can have. Fields can be of two types: custom and TBX compatible.

• Incremental next value

GET /api/v4/fields/incremental/next/{field-oid}

Description

Returns next available value for fields of type "incremental"

Request documentation
Path parameters

field-oid string

Field old object oid of field of type "incremental"
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Value with next available number
• Incremental validate value

GET /api/v4/fields/incremental/validate/{field-oid}

Description

Check uniqueness of value for specified field of type "incremental".

Request documentation
Query parameters

field-oid string

Field old object oid of field of type "incremental"

value number

value to check

type enum

One of the field levels: CONCEPT or TERM

entry-id number

<optional>, Concept or Term id to exclude from validation results.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body boolean

true when provided value is unique
• Generate picklist from text values

GET /api/v4/fields/generate-picklist/{field-oid}

Description

Returns next available value for fields of type "incremental"

Request documentation
Path parameters

field-oid string

Field old object oid of field of type "incremental"
Query parameters

multivalued boolean

<optional>, default is true. Pass true when you’re generating values for multivalued picklist. It will parse
values additionally by using as separator value of multivalued.separator from termweb.properties file.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body PickListItem[]

Picklist items generated from text values of specified field. An array of objects of type Picklist item.

13.5.4. Domains endpoint

Description

Domains for Dictionary. Domains linked together in hierarchical structure.

• Domain DTO
Object attribute Description

name string

Domain name.

dictionaryId number

Dictionary id in which that language has been created.

parentDomainId number

Domain id which is parent of this domain.

numberOfConcepts number

Number of concepts created in this section

children number[]

List of children Domain ids.

clientId number

Client id to which object belongs

id number

Domain id.

oid string

Domain oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• DomainConfig
Object attribute Description

presentation enum

Setting how to represent selected domains for Concept in a concept view.
Possible values are:
FLAT every selected Domain will be printed on separate lane with full path to it
HIERARCHICAL show all selected domains ordered list
HORIZONTAL everything is represented in one line, separated by square bullets, domains on a same level and parent are grouped.
• Find

GET /api/v4/domains/

Description

Finds domain with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

required, provide a dictionary id to get list of domains for it.

name string

<optional>, default is null
Filters domain with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters domain with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Domain[]

Found domain of type Domain.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/domains/rownum/{id}

Description

Finds rownumber of domain with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Domain id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

required, provide a dictionary id to get list of domains for it.

name string

<optional>, default is null
Filters domain with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters domain with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/domains/{id}

Description

Looks for domain with specified id.

Request documentation

Path parameters

id number

Domain id to look for

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Domain

JSON object of Domain.
• Create

POST /api/v4/domains/

Description

Creates new domain from JSON data sent in payload.

Request documentation

Payload

body Domain

JSON object of type Domain.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Domain

Created object of domain.
• Update

PUT /api/v4/domains/{id}

Description

Updates existing domain from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Domain which need to be updated

Payload

body Domain

JSON object of type Domain. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Domain

Updated domain object.
• Partial update

PUT /api/v4/domains/partial/{id}

Description

It updates only specified parts of domain from JSON data sent in payload. Unlike method PUT /api/v4/domains/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Domain which need to be updated

Payload

body Domain

JSON object of type Domain. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for domain objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Domain

Patched domain object.
• Delete

DELETE /api/v4/domains/{id}

Description

Deletes domain with specified id.

Request documentation

Path parameters

id number

Domain id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/domains/async/{id[]}

Description

Deletes domain with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Domain ids of domain to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is domain id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.
• Get Domains config

GET /api/v4/domains/{dictionaryId}/config

Description

This operation retrieves a current Domains configuration from server for current Dictionary.

Request documentation

Path parameters

dictionaryId number

Dictionary id to look for
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body BimaConfig

Response of type DomainConfig.
• Update Domains config

POST /api/v4/domains/{dictionaryId}/config

Description

This operation updates Domains configuration for current Dictionary

Request documentation

2+h|Path parameters |dictionaryId number |Dictionary id to update

Request body DomainConfig

Domains configuration to set DomainConfig
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DomainConfig

Updated configuration from server described with type DomainConfig.

13.5.5. Filters endpoint

Description

If you want to search for term records or term equivalents that fulfill specific criteria, e.g. all term records that do not have a definition, term records that do not have a term equivalent in a certain language or term equivalents in a certain language with a certain status, you can use the filter function.

Note! A filter limits the search to the selected dictionary (current main dictionary). A filter can be defined to be private (only accessible for the creator) by setting its visibility to Owner or accessible for a certain group selected in the Visibility dropdown, or to all users, if All users group is selected in the Visibility dropdown. However, only the owner of the filter, or an administrator, can edit or delete a filter.

If an administrator is unable to delete a filter, it is because it is in use (in an Export settings or as a standard filter for a Group).

You can use several combinations of conditions in the filter.

Filters can also be applied to term export. The filter is then chosen under Export settings in the Select concepts by filter field.

The conditions for the field contents can be set as follows:

  • fields that contain an exact string (typed after EQUALS)

  • fields empty or not (used with EMPTY or NOT_EMPTY)

  • fields that contain the string and additional contents (typed after CONTAINS)

  • fields that do not contain the string (typed after NOT CONTAINS)

  • fields that are not equivalent to a specific string (typed after NOT EQUALS)

  • fields that start with a certain string (typed after STARTS WITH)

  • for certain fields: that fulfill a specific time value, e.g. that were changed before (BEFORE) or after (AFTER) a specific point in time (date and time) or on a specific date (EQUALS), or outside a specific date (NOT EQUALS)

  • for numeric fields: where the field value EQUALS, NOT EQUALS, is LESS THAN or GREATER THAN a typed-in integer value

You can create a temporary filter which can be used with term search request as Quick Filter.

• Filter DTO
Object attribute Description

name string

Filter name.

groupId number

Group id to which this Filter available to use. Used for "Visibility" field in UI.
When value is null this means filter visible only to author and Client administrator.

filteringTerms boolean

true when search results will return only matching terms. Otherwise it will return all terms from Concept containing matching term. ()

criterias FilterCriteria[]

Original developer of this functionality didn’t know that criteria is the plural form of criterion and indices, and not indexes, is correct plural form of index.
Later these field names will be updated to have the correct grammatical form.
List of filter criteria of type Filter criterion.

indexed boolean

true when TermWeb processed filter and indexed all terms.

type enum

Filter type. Possible values are: STANDARD, TEMPORARY, SEARCH_FIELD, PROJECT, DUAL, SYNC_SETTING.

canEdit boolean

true when filter can be edited by current user.

cantDelete boolean

true when filter can’t be deleted by current user.

cantDeleteReason string

Message containing information why this filter can’t be deleted.

dictionaryId number

Dictionary id to which filter related.

clientId number

Client id to which object belongs

id number

Filter id.

oid string

Filter oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Filter criterion DTO
Object attribute Description

filterId number

Filter id to which this criterion belongs.

fieldOid string

Field old object oid from dictionary to which this Filter belongs to.
Can have here system field oid instead of regular dictionary field: DOM - concepts domain,
DICT - dictionary,
SECT - dictionary sections,
SUBC - subclass, not in use,
CONID - Concept ID (serial number in dictionary),
CREBY - concept created by,
CREDATE - concept creation date,
CHGBY - last author of concept changes,
CHGDATE - concept last modification date,

TERM - term name,
LANG - term language,
GVAR - geographical variant,
OVAR - orthographical variant,
TERM_CONFIG - internal use only,
TCREBY - term created by,
TCREDATE - term creation date,
TCHGBY - term last author of term changes,
TCHGDATE - term last modification date,
TERM_ID - Term ID (serial number in dictionary) .

To split up concept level fields criteria and term level fields criteria used special fieldOid value equal to 'TERM_CRI_START'.
Filter can have multiple groups of term level fields criteria. Terms criteria can’t be nested into each other.
There is NO special fieldOid 'TERM_CRI_END' as you may think.

conceptField boolean

true when this condition is for concept level field.

operation enum

Comparison operation for this field, can have this values: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, EXISTS, NOT_EXISTS, LESS_THAN, GREATER_THAN, STARTS_WITH, EMPTY, NOT_EMPTY .

value string

String value to use with operation. When search is done on non text field types, value must another value than text. In case of field type:

  • User: User old object oid.

  • Domain: Domain old object oid.

  • Concept Id: Concept cid (serial number in Dictionary).

  • Date: Date string in one of the formats: yyyy-MM-dd HH:mm:ss, yyyy-MM-dd HH:mm, yyyy-MM-dd, yyyyMMdd. Please note that these dates will be converted to the server’s time zone which is UTC by default. .

  • Section: Section old object oid.

  • Term: Term name attribute.

  • Language: should be ISO639-2 three-letter lower case code.

  • Region: Language Variant old object oid for geographical variant.

  • Script: Language Variant old object oid for orthographical variant.

  • Picklist: Picklist item name attribute when it has value, otherwise - tbxName value.

boolOperator enum

Number enum which indicates how current criterion linked with next criterion in array.
Values are: 'No operator' - 0, 'AND operator' - 1, 'OR operator' - 2.

type enum

Filter type. Possible values are: STANDARD, TEMPORARY, SEARCH_FIELD, PROJECT, DUAL, SYNC_SETTING.

sortIndex number

Order number where this criterion must be in an array of filter criteria.

relDate boolean

true when date condition is used as relative date (TermWeb will update date condition relatively to date of creation).

included boolean|null

Used in combination with fieldOid equal to 'TERM_CRI_START' otherwise will be null. true means that matched values will be included into search results, otherwise - excluded.

id number

Filter criterion id.

oid string

Filter criterion oid. This is object id from old objects.
• Index filter

POST /api/v4/filters/index/{id}

Description

Launches indexing of Filter. Operation is synchronous.

Request documentation

Path parameters

id number

Filter id.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful index.
• Find

GET /api/v4/filters/

Description

Finds filters with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter filter criterion objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters filters with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters filters with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Filter[]

Found filters of type Filter.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/filters/rownum/{id}

Description

Finds rownumber of filter criterion with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Filter criterion id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter filter criterion objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters filters with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters filters with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/filters/{id}

Description

Looks for filter criterion with specified id.

Request documentation

Path parameters

id number

Filter criterion id to look for

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Filter

JSON object of Filter criterion.
• Create

POST /api/v4/filters/

Description

Creates new filter criterion from JSON data sent in payload.

Request documentation

Payload

body Filter

JSON object of type Filter.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Filter

Created object of filter criterion.
• Update

PUT /api/v4/filters/{id}

Description

Updates existing filter criterion from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Filter criterion which need to be updated

Payload

body Filter

JSON object of type Filter. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Filter

Updated filter criterion object.
• Partial update

PUT /api/v4/filters/partial/{id}

Description

It updates only specified parts of filter criterion from JSON data sent in payload. Unlike method PUT /api/v4/filters/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Filter criterion which need to be updated

Payload

body Filter

JSON object of type Filter. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for filter criterion objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Filter

Patched filter criterion object.
• Delete

DELETE /api/v4/filters/{id}

Description

Deletes filter criterion with specified id.

Request documentation

Path parameters

id number

Filter criterion id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/filters/async/{id[]}

Description

Deletes filters with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Filter criterion ids of filters to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is filter criterion id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.5.6. Views endpoint

Description

Client administrator or dictionary administrator should be able to create/edit view for Dictionary, and also be able to delete Views which are not in use. When view is in use (by Group, Section) UI should provide information why it can’t be deleted.

Dictionary can be changed for View during edit (only when View is not in use by any Group or Section).

'Term' and 'Language' fields are always visible and can’t be hidden.

• View DTO
Object attribute Description

name string

View name.

fields string[]

Field oids included in this view.

inUse boolean

true when view is in use by any Section or by Group.

inUseMessage boolean

Message with a description of which views or groups are using that view.

dictionaryId number

Dictionary id to which view related.

clientId number

Client id to which object belongs

id number

View id.

oid string

View oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Find

GET /api/v4/views/

Description

Finds views with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter view objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters views with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters views with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content View[]

Found views of type View.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/views/rownum/{id}

Description

Finds rownumber of view with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

View id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter view objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters views with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters views with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/views/{id}

Description

Looks for view with specified id.

Request documentation

Path parameters

id number

View id to look for

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body View

JSON object of View.
• Create

POST /api/v4/views/

Description

Creates new view from JSON data sent in payload.

Request documentation

Payload

body View

JSON object of type View.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body View

Created object of view.
• Update

PUT /api/v4/views/{id}

Description

Updates existing view from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of View which need to be updated

Payload

body View

JSON object of type View. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body View

Updated view object.
• Partial update

PUT /api/v4/views/partial/{id}

Description

It updates only specified parts of view from JSON data sent in payload. Unlike method PUT /api/v4/views/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of View which need to be updated

Payload

body View

JSON object of type View. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for view objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body View

Patched view object.
• Delete

DELETE /api/v4/views/{id}

Description

Deletes view with specified id.

Request documentation

Path parameters

id number

View id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/views/async/{id[]}

Description

Deletes views with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

View ids of views to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is view id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.5.7. Export settings endpoint

Description

Export settings defines what fields, languages and terms to export from dictionary. Currently, endpoint is working only in read-only mode.

• Export settings DTO
Object attribute Description

name string

Export settings name.

dictionaryId number

Id of Dictionary for which these settings are used.

visibility enum

Visibility of settings. Possible values are: PRIVATE, PUBLIC.

userId number

Id of owning User these settings.

fileFormat enum

Export file format. Possible values are: TBX, EXCEL, MULTITERM_IX.

fileName string

File name to use when saving result file.

exportPermalinks boolean

true when reference links replaced with actual links to server.

exportAttachments boolean

true when export should include file attachments.

exportOneSheet boolean

true to export all sections into one Excel sheet.

filterId number

Id of Filter used by these settings to filter out concepts. Can be null.

selectedLanguages string[]

An array of Language codes (code3) selected to be included in export. Not null.

selectedConceptFields string[]

An array of concept level Field oids selected to be included in export. Not null.

selectedTermFields string[]

An array of term level Field oids selected to be included in export. Not null.

orderTermByField string

Oid of TERM level Field to sort terms in a Excel sheet.

neverLaunched boolean

true when these export settings has never been launched.

id number

Export settings id.

oid string

Export settings oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Find

GET /api/v4/export-settings/

Description

Finds export settings with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter export settings objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters export settings with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters export settings with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for export settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content ExportSettings[]

Found export settings of type Export settings.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/export-settings/rownum/{id}

Description

Finds rownumber of export settings with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Export settings id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter export settings objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters export settings with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters export settings with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for export settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/export-settings/{id}

Description

Looks for export settings with specified id.

Request documentation

Path parameters

id number

Export settings id to look for

format enum

<optional>, default is 'FULL'
Response format for export settings objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body ExportSettings

JSON object of Export settings.

13.6. Terminology

13.6.1. Concepts endpoint

Description

Concepts are a key part of the TermWeb object structure. They join together related terms from different languages. To avoid data duplication users can define concept level fields which will have common attributes, like; definition, source reference, figure, picture, domain, usage note, etc.

• Concept DTO
Object attribute Description

cid string

Concept ID. Serial number of this concept in Dictionary. Don’t confuse with object id which is unique for whole TermWeb installation and cid unique only for one Dictionary.

sectionOid string

Section old object oid to which this Concept belongs to.

domainList string[]

Domain old object oids to which this Concept related.

terms Term[]

An array of terms related to this Concept.

conceptRelations ConceptRelation[]

An array of Concept relation link objects.

languageCodesEditable string[]

A list of language codes which can be edited by current user. Language code is ISO639-2 three-letter lowercase code.

permissions Map<ConceptPermission,boolean>

A map of Concept permissions for current user. When user has permission to perform some operation, map will have value true.

fieldMap Map<string,string[]>

The map of Field oids and values. Only fields with non-empty values should be included in the map. Line breaks in the value should be encoded as CR LF (\r\n) to correspond with reflink positions.
Only fields with type MULTISELECT can have multiple values.

refLinks RefLink[]

List of RefLinks created for current concept.

comments Comment[]

List of last comments created for this concept.

dictionaryId number

Dictionary id to which concept related.

clientId number

Client id to which object belongs

id number

Concept id.

oid string

Concept oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Concept permissions enum
Value Description

CONCEPT_EDIT_FIELDS string

The user can edit concept level fields.

CONCEPT_UPDATE string

The user can edit a concept or restore changes in history.

CONCEPT_DELETE string

The user can delete a concept.

CONCEPT_PRINT string

The user may print a concept.

CONCEPT_VIEW_HISTORY string

The user can see change history for concepts.

RESTORE_STATE string

The user can restore to state in concept history.

TERM_CREATE string

The user is allowed to create new terms and restore deleted terms from history.
• Concept Relation DTO
Object attribute Description

dictionaryId number

Dictionary id in which that relation has been created.

sourceConceptId number

Source Concept id of this relation.

targetConceptId number

Target Concept id of this relation.

type enum

Concept relation type, value is numeric. Possible values are: 'GENERIC' - 0, 'PARTITIVE' - 1, 'TEMPORAL' - 2, 'SPATIAL' - 3, 'ASSOCIATIVE' - 4

attribute enum

Concept relation attribute, depends on value of type attribute. Possible values are: 'GENERIC_SUPERORDINATE' - 0, 'GENERIC_SUBORDINATE' - 1,
'PARTITIVE_SUPERORDINATE' - 2, 'PARTITIVE_SUBORDINATE' - 3,
'TEMPORAL_BEFORE' - 4, 'TEMPORAL_CONCURRENT' - 5, 'TEMPORAL_AFTER' - 6,
'SPATIAL_UP' - 7, 'SPATIAL_DOWN' - 8, 'SPATIAL_RIGHT' - 9, 'SPATIAL_LEFT' - 10,
'ASSOCIATIVE_DEFAULT' - 11

text string

Relation specification text.

relationId number

Serial number for this relation. Unique per Dictionary. Assigned by the server on creation.

id number

Concept relation id.

oid string

Concept relation oid. This is object id from old objects.
Object attribute Description

sourceConceptId number

Concept id to which this cross-reference belongs.

sourceTermId number

Term id to which this cross-reference belongs, will be null in case of concept level field.

sourceFieldOid string

Field oid where this cross-reference must be rendered.

type enum

Cross-reference type defines what it contains. Possible values are: UNKNOWN_LINK_TYPE = 0, TERM_LINK_TYPE = 1, CONCEPT_LINK_TYPE = 2, EXTERNAL_LINK_TYPE = 3, TERM_LINK_DYNAMIC_TYPE = 4.

text string

Original reference text.

dynamicText string

In case of TERM_LINK_DYNAMIC_TYPE this will contain the latest term value from termId property. Otherwise, it will be the same as text property.

position number

At which position in the text the link starts. If the text contains line breaks these are considered to be encoded as CR LF (\r\n), so every line break adds two characters to the position of links in following text rows.

url string

In case of EXTERNAL_LINK_TYPE this will contain URL to external website or to TermWeb file. Links to TermWeb files always starts with custom protocol, like termweb://files/{fileId};

conceptId number

Concept id to which ref link points in case of internal cross-reference.

termId number

Term id to which ref link points in case of TERM_LINK_TYPE or TERM_LINK_DYNAMIC_TYPE cross-reference.

languageCode string

Language code3 to ref link points in case of TERM_LINK_TYPE or TERM_LINK_DYNAMIC_TYPE cross-reference.

dictionaryId number

Dictionary id to which ref link related.

invalid boolean

true when it points to something missing or incorrect position, etc.

id number

RefLink id.

oid string

RefLink oid. This is object id from old objects.

• Get by id

GET /api/v4/concepts/{id}

Description

Looks for concept with specified id.

Request documentation

Path parameters

id number

Concept id to look for

Query parameters

with-comments boolean

<optional>, true when to include concept comments to response.

format enum

<optional>, default is 'FULL'
Response format for concept objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of Concept.
• Get by [oid, term-oid, term-id]

GET /api/v4/concepts/

Description

Looks for concept with by one of the specified parameters. At lease of one the parameters must be present. Server will process only one parameter at a time.

Request documentation

Path parameters

oid number

<optional> Concept oid to look for

term-oid number

<optional> Term oid to look for

term-id number[]

<optional> An array of Term id to look for

Query parameters

with-comments boolean

<optional>, true when to include concept comments to response.

format enum

<optional>, default is 'FULL'
Response format for concept objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of Concept. Or an array of Concept in case of multiple values in term-id parameter.
• Create

POST /api/v4/concepts/

Description

Creates new concept from JSON data sent in payload.

Request documentation

Payload

body Concept

JSON object of type Concept.

format enum

<optional>, default is 'FULL'
Response format for concept objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

Created object of concept.
• Update

PUT /api/v4/concepts/{id}

Description

Updates existing concept from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Concept which need to be updated

Payload

body Concept

JSON object of type Concept. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for concept objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

Updated concept object.
• Partial update

PUT /api/v4/concepts/{id}/patch

Description

It updates only specified parts of concept from JSON data sent in payload. Unlike method PUT /api/v4/concepts/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON. For example when Concept have terms property with actual values in array, server will update it, when term equal to null none of terms will be updated.

Request documentation

Path parameters

id number

Id of Concept which need to be patched

Payload

body Concept

JSON object of type Concept. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for concept objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

Patched concept object.
• Delete

DELETE /api/v4/concepts/{id}

Description

Deletes concept with specified id.

Request documentation

Path parameters

id number

Concept id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Print as HTML

GET /api/v4/concepts/{id}/print-as-html

Description

Generates html preview of concept for specified id.

Request documentation

Path parameters

id number

Id of Concept which need to be printed
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body

Body containing HTML text.
• Permissions

GET /api/v4/concepts/{id}/permissions

Description

Looks for current user concept permissions with specified id for specific Dictionary section.

Request documentation

Path parameters

id number

Concept id to look for

Query parameters

section-oid string

Section old object oid.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of Concept with filled permission values for concept and its terms. See Concept permissions.

13.6.2. Terms endpoint

Description

This endpoint is mostly responsible for executing search and providing results.

• Term DTO
Object attribute Description

name string

Term itself.

tid string

Term ID. Serial number of this term in Dictionary. Don’t confuse with object id which is unique for whole TermWeb installation and tid unique only for one Dictionary.
tid consists of two parts: Concept cid + '-' <unique serial number of that term inside of concept>, like 100-5.

conceptId number

Concept id to which this term belongs.

conceptOid string

Concept old object oid to which this term belongs.

languageCode string

Language code. Should be ISO639-2 3-char lower case code.

regionCode string

Geographical Language Variant code for this term if set.

scriptCode string

Orthographical Language Variant code for this term if set.

permissions Map<TermPermission,boolean>

A map of Term permissions for current user. When user has permission to perform some operation, map will have value true.

fieldMap Map<string,string[]>

The map of Field oids and values. Only fields with non-empty values should be included in the map. Line breaks in the value should be encoded as CR LF (\r\n) to correspond with reflink positions.
Only fields with type MULTISELECT can have multiple values.

refLinks RefLink[]

List of RefLinks created for current term.

comments Comment[]

List of last comments created for this term.

dictionaryId number

Dictionary id to which term related.

clientId number

Client id to which object belongs

id number

Term id.

oid string

Term oid. This is object id from old objects.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Term permissions enum
Value Description

TERM_UPDATE string

The user can edit a term or restore changes in history.

TERM_DELETE string

The user can delete a term.

POST /api/v4/terms/search

Description

Searches for terms form specified dictionaries.

Request documentation

Payload fields TermSearchRequest

dictionaryIds number[]

required, An array of Dictionary ids. Typically used to search from one dictionary, but more than one can be specified.

langCode string

required, Should be ISO639-2 three-letter lower case code.

regionCode string

<optional>, Geographical Language Variant code for this term if set.

scriptCode string

<optional>, Orthographical Language Variant code for this term if set.

filterId number

<optional>, Filter id to use with search.

sectionOids string[]

required, List of Section old object oids to include in search.

domainOids string[]

<optional>, To filter by domains provide a list of Domain old object oids.

quickFilter Filter

<optional>, temporary filter to quickly apply it to search results without creating normal filter. Object of type Filter.

name string

<optional>, Term name to search, or text to search in case of multi field search.

pageSize number

<optional>, Amount of entries to return.

termOid number

<optional>, Term oid. When provided search will look for that Term with terms around it.

searchAfter Object[]

<optional>, internal value with index from which continue next search call to load next page of search results. Can be obtained from TermSearchResponse.

reverse boolean

true when search results are loading backwards.

bidirectional boolean

Can be used only with combination of termOid attribute. true when to load search results surrounding requested term before and after. Otherwise requested Term will be first in search results.

searchOptions.normalized boolean

true to enable normalized search for symbols with length more than 2-byte.

searchOptions.fuzzy boolean

true enable approximate string matching, also known as fuzzy string searching, in search results.

searchOptions.multiEnabled boolean

true when search must include field to values into search. false look as usual only term name.

searchOptions.multiAllFields boolean

true when search must be done in all fields.

searchOptions.fields Map<FieldLevel,Set<string>

A collection of selected Field oids for multi-field search. FieldLevel is enum with values: CONCEPT and TERM.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body TermSearchResponse

Search results object of type TermSearchResponse.
• TermSearchResponse
Object attribute Description

total number

Total number of terms available with current search params. Can be unknown in case of complicated search params, result then will be -1.

pageSize number

Page size of search results.

searchAfter Object[]

Internal value with index from which continue next forward search call.

searchBefore Object[]

Internal value with index from which continue next backward search call.

results TermListEntry[]

Found entries for current search results of type TermListEntry.

message string

Server message containing warning or error description.
• TermListEntry
Object attribute Description

id number

Term id.

name string

Term name.

dictionaryId number

Dictionary id to which Term related.

termId string

Term tid value.

conceptId number

Concept id.

conceptOid string

Concept oid.

langCode string

ISO639-2 three-letter lower case language code

filterId number

Filter id matched this term. Deprecated.

style string

Value for HTML attribute style. May contain results of conditional formatting from Workflow.

disabled boolean

Term is read-only when value is true.

hidden boolean
• Suggestion

POST /api/v4/terms/suggestion

Description

Endpoint for creating Term suggestions in configured Dictionary.
Term suggestion may contain new language or TBX field.

Request documentation
Payload fields TermSuggestionRequest

conceptFields Map<string,string>

A map of Field values. As key can be used Field.oid, Field.name or Field.dataCategory if a Field is TBX.

terms TermSuggestion[]

A list of TermSuggestions to be created in a single Concept.
• TermSuggestion
Object attribute Description

term string

Term name sugestion.

langTag string

BCP-47 language tag. List of supported language codes is ISO639-2 plus several extensions from ISO639-3.

fields Map<string,string>

A map of Field values. As key can be used Field.oid, Field.name or Field.dataCategory if a Field is TBX.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Term.id of created suggestion.
• Get by terms ids

GET /api/v4/terms/duplicates

Description

Looks for Terms duplicates.

Request documentation
Query parameters

term string

Term name to check for duplicates

dictionary-id string

Dictionary where to look for duplicate terms.

lang-code string

ISO639-2 three-letter lower case language code.

concept-id number

<optional>, Concept id which must be excluded from search results.

region-code string

<optional>, geographical Language Variant code to look for.

script-code string

<optional>, orthographical Language Variant code to look for.

size number

<optional>, default is 10
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

content TermListEntry[]

Found terms of type TermListEntry.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number

13.6.3. Display concepts endpoint

Description

This endpoint is used for getting prepared Concept for display. It contains applied Workflow functions, conditional formatting and views.

It can, for example, set default values to fields on creation or edit.

Please note this endpoint is subject to change in future. It will be merged with Concepts endpoint.

• Display Concept DTO
Object attribute Description

sectionId number

Section id to which concept belongs.

requestedByUserId number

User id which requested this concept.

classificationFields DisplayField[]

List of concept classification fields of type Display field. This list can have fewer fields than original entry.

languageCodes string[]

Language codes of terms which are present in concept. Codes are ordered according to Language sortIndex.

termsPerLanguage List<List<DisplayTerm>>

Terms of type Display term grouped by language code assigned on same position in languageCodes attributes.

termSelected boolean

true when display concept has been created with selected term.

concept Concept

Original object of type Concept.

id number

Display concept id.

dictionary_id number

Dictionary id to which display concept related.

metadataFields DisplayField[]

List of display concept metadata fields of type Display field. This list can have fewer fields than original entry.

fields DisplayField[]

List of display concept fields of type Display field. This list can have fewer fields than original entry.
• Display Term DTO
Object attribute Description

langCode string

Language code for a term. In case of custom language will have full language tag.

region string

In case of standard language can have code of geographical variant (usually country code.)

script string

In case of standard language can have code of orthographical variant (usually script code.

elementId string

Element id for a term consisting of prefix 'T' + term.oid

termField DisplayField

Display field for term name.

id number

Display concept id.

dictionary_id number

Dictionary id to which display concept related.

metadataFields DisplayField[]

List of display concept metadata fields of type Display field. This list can have fewer fields than original entry.

fields DisplayField[]

List of display concept fields of type Display field. This list can have fewer fields than original entry.
• Display Field DTO
Object attribute Description

id string

Field old object oid.

label string

English name of Field.

value string[]

Processed and prepared for display value of field from entry.

valueOid string[]

In case when value is related to another object like Dictionary, Section or it has picklist type, this array will contain that objects oids.

cssClass string

CSS class name for an element displaying that field.

cssStyle string

CSS style for an element displaying that field.

readOnly boolean

true when value must read only.

hidden boolean

true when field must not be displayed to user.
• Get

GET /api/v4/display-concepts/{id}

Description

Looks for display concept with specified id.

Request documentation

Path parameters

id number

<optional> id of Concept to look for.

Query parameters

term-id number

Term id to look for.

load-concept boolean

<optional>, default value true, returns original concept together with response.

with-comments boolean

<optional>, default value false, loads with Concept object user comments too.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayConcept

JSON object of Display concept.
• Create

POST /api/v4/display-concepts/create/{dictionary-id}

Description

Creates new display concept for specified dictionary. Concept is not persisted to database. It creates only stub for a concept with applied workflow functions.

Request documentation

Path parameters

dictionary-id number

Dictionary id where to create new concept.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayConcept

Created object of display concept.
• Edit

PUT /api/v4/display-concepts/edit/{concept-id}

Description

Creates edit version display concept for specified concept. Concept is not persisted to database. It applies workflow functions to a concept on edit start.

Request documentation

Path parameters

concept-id number

Concept id which need to process.

Query parameters

term-id number

Term id - selected term.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayConcept

Created object of display concept.
• Copy

POST /api/v4/display-concepts/copy/{concept-id}

Description

Creates new display concept by copying specified concept. New concept is not persisted to database. It creates only stub for a concept with applied workflow functions.

Request documentation

Path parameters

concept-id number

id of Concept to copy.

Request parameters

term-id number

<optional> Id of selected Term which can be used by workflows for future usage.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayConcept

Created object of display concept.
• Add term

POST /api/v4/display-concepts/add-term/{concept-id}

Description

Creates new Display term for specified concept. New term is not persisted to database. It creates only stub for a term with applied workflow functions.

Request documentation

Path parameters

concept-id number

id of Concept where to create new term.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayTerm

Created term of DisplayTerm.
• Copy term

POST /api/v4/display-concepts/copy-term/{term-id}

Description

Creates new Display term by copying specified term. New term is not persisted to database. It creates only stub for a term with applied workflow functions.

Request documentation

Path parameters

term-id number

id of Concept where to create new term.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body DisplayTerm

Created copy of term.

13.6.4. Comments endpoint

Description

Simplified version of comments.

• Comment DTO
Object attribute Description

text string

Comment text.

authorName string

Full name of comment author.

userId number

User id of comment author.

dictionaryId number

Dictionary id to which comment related.

fieldLevel enum

Field level enum which helps to determine type of entry. Possible values are: CONCEPT or TERM.

entryId number

Concept id or Term id for which this comment created.

date number

Creation date and time of comment in milliseconds since Unix Epoch until license is valid.

id number

Comment id.

oid string

Comment oid. This is object id from old objects.
• Find

GET /api/v4/comments/

Description

Finds comments with specified entry id.

Request documentation

Query parameters

entry-id number

Concept id or Term id to look for.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Comment[]

An array of comments of type Comment.
• Create

POST /api/v4/comments/

Description

Creates new comment from JSON data sent in payload.

Request documentation

Query parameters

entry-id number

Concept id or Term id where to create new comment.

Payload

body Comment

JSON object of type Comment containing only filled "text" attribute.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Comment

Created object of comment.
• Delete

DELETE /api/v4/comments/{id}

Description

Deletes comment with specified id.

Request documentation

Path parameters

id number

Comment id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

13.6.5. History items endpoint

Description

View changes in the overall structure and History content of a dictionary and “undo” the ones you do not want. If you want to “undo” changes (i.e. restore previous data) for a specific term.

• History Item DTO
Object attribute Description

id number

history item id.

oid string

history item oid. This is object id from old objects.
• Find dictionary history

GET /api/v4/history/concept/{concept-id}

Description

Returns a page of history items for requested concept.

Request documentation
Path parameters

concept-id number

Concept id where to look for history items.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content HistoryItem[]

Found history items of type History item.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Find dictionary history

GET /api/v4/history/dictionary/{dictionary-id}

Description

Returns a page of history items for requested dictionary. Because of current limitations, history items can only be retrieved since last Dictionary structure change.

Request documentation
Path parameters

dictionary-id number

Dictionary id where to look for history items.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content HistoryItem[]

Found history items of type History item.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Undo concept

POST /api/v4/history/concept-undo/

Description

Undoing concept changes to specified concepts state in history item.

Request documentation

Query parameters

history-item-id number

History item id to which we need to restore concept state.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Concept

JSON object of restored Concept object.
• Undo dictionary

POST /api/v4/history/dictionary-undo/

Description

Undoing any changes in Dictionary to specified state in history item.

Request documentation

Query parameters

history-item-id number

History item id to which we need to restore dictionary state.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful transfer or 204 Accepted when operation is still restoring.

Payload attributes InvocationResult

result boolean

true when dictionary successfully restored to requested state.

jobTaskId number

When operation went to asynchronous transfer, this value will have id of running job task. See JobTask.

13.7. UI settings

13.7.1. User data endpoint

The endpoint provides initial data for authentication token required to setup UI client

• Session data DTO
Object attribute Description

user User

Current user object of type User.

roles Role[]

An array of assigned user roles Role.

isSystem boolean

true if current user is System administrator

activeClientIds number[]

An array containing one Client id used for login.

clients Client[]

An array of Clients available to user work with. User can switch session to this client via POST /api/v4/switch-client.

dictionaries Dictionary[]

An array of Dictionaries available to user for search and read terms.

filters Filter[]

An array of Filters available to user for use

settings SearchSettings[]

Current user’s Search settings.

preferences UserPreferences[]

Current user’s User preferences.

stagingAreas StagingArea[]

An array of Staging areas available to user.

permissions UIPermissions

User’s UIPermissions allowing to use functions of TermWeb.

sessionTimeout number

User session timeout value if it is not equal to default session timeout defined in GET /api/v4/system/features

welcomePageVersion number

Last available welcome page version

feedbackEnabled boolean

Feedback function is enabled and messages can be sent via POST /api/v4/feedback.
• UIPermissions
Object attribute Description

quickFiltersEnabled boolean

User is not allowed to work with quick filters via Filters endpoint.

searchModesEnabled boolean

User is not allowed to change searchOptions in POST /api/v4/terms/search.

gridViewEnabled boolean

true if current user allowed to work with Staging areas endpoint

commentsEnabled boolean

User can read and write comments for Concept
• Get initial data

GET /api/v4/data

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body SessionData

JSON object of Session data.

13.7.2. Feedback page endpoint

Feedback page configuration endpoint. It allows to retrieve current settings and change it

• FeedbackPage DTO
Object attribute Description

enabled boolean

Current status of Feedback page function. true when feedback is active.

title string

Title to show on top of Feedback modal dialog

header string

First line of dialog contents written as html header.

headerDescription string

Second line of dialog contents written as html paragraph under header.

useDictionaryRecipient boolean

When set to true TermWeb will try to find recipient in Dictionary property emailRecipientId. If Dictionary doesn’t have recipient, or recipient doesn’t have an email, then recipientEmails will be used.

recipientEmails string[]

An array of emails where to send feedback from users.

recipientUserIds number[]

An array of User ids where to send feedback from other users.

defaultSubject string

Text subject for prefilling in modal dialog.

messagePlaceholder string

Placeholder message text to place inside of textarea

bottomDescription string

Last line of dialog contents written as html paragraph before submit buttons.
• Get Feedback page configuration

GET /api/v4/ui/feedback-page

Returns current feedback page configuration for current session’s Client.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body FeedbackPage

Current feedback page configuration of type Feedback page.
• Update Feedback page configuration

PUT /api/v4/ui/feedback-page

Updates feedback page configuration for current session’s Client.

Request documentation
Payload

body FeedbackPage

New feedback page configuration of type Feedback page.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body FeedbackPage

Updated feedback page configuration of type Feedback page.

13.7.3. Welcome page endpoint

Welcome page configuration endpoint. It allows to retrieve current page and change it.

• Get Welcome page configuration

GET /api/v4/ui/welcome-page

Returns current welcome page contents for current session’s Client.

Request documentation

Headers

X-Auth-Token

Unexpired authentication token

Request parameters

v

Numeric value of welcome page version. Latest number of version can be found in Session data.
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Cache-Control

max-age=604800

Payload

body string

String containing welcome page html contents
• Update Welcome page

PUT /api/v4/ui/welcome-page

Updates welcome page contents for current session’s Client. Most of the html formatting elements allowed. <style> and <script> elements will be removed.

Request documentation
Payload

body _string

New welcome page html contents.
Response documentation

Status

code number

200 OK in case of successful update

Payload

body number

New version number of updated page

13.7.4. Menu endpoint

Because TermWeb is a hybrid app with combination of server rendering and single page application. We need to share state of menu items between that two parts.

• Menu item DTO
Object attribute Description

href string

URL for opening current Menu item.

parentHref string

URL of parent Menu item containing current item.

title string

Descriptive text to put it into html title attribute.

label string

Short text used for showing as menu item text.

icon string

CSS classes to use as icon. Normally Fontawesome.

v4 boolean

true when this Menu item points to new page from TermWeb 4, and false when it points to server rendered page from TermWeb 3.

disabled boolean

true when user can’t access to this page. For example when there are no dictionaries in TermWeb, user can’t open Filters page.

old MenuItem

Menu item object pointing to previous implementation from TermWeb 3 in case when it exists. Otherwise, this attribute won’t be present.
• Get Top menu

GET /api/v4/ui/menu/top

Returns top menu items for Administration View.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body MenuItem[]

An array of menu items available to user of type Menu item.
• Get Side menu

GET /api/v4/ui/menu/side/{idx}

Returns side menu items related to specified top menu idx.

Request documentation
Path parameters

idx string

Top menu item serial number from returned an array of items.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body MenuItem

JSON object of Menu item.

13.7.5. Profile endpoint

Methods to work with personal and account data for users.

• Profile DTO
Object attribute Description

user User

Current user information of type User

preferences User

Current user preferences User preferences

lastLogins UserLogItemDto[]

10 last records of current user logins UserLogItem
• UserPreferences DTO
Object attribute Description

userId number

Current user id

preferences Map<PreferenceKey,string[]>

Current user’s preferences.
• PreferenceKey key

Enum key used by User preferences to store properties.

Object attribute Description

DISPLAY_DATE_FORMAT

Date format, default value yyyy-MM-dd

DISPLAY_TIME_FORMAT

Time format, default value HH:mm
• Get profile

GET /api/v4/profile/

Returns profile data for current user.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

JSON object of Profile.
• Update profile

PUT /api/v4/profile/

Request documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

User data of type Profile to update.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

Updated data of type Profile.
• Change password

PUT /api/v4/profile/password

Updates user password. Password must fulfill validation password rules, otherwise server will reject new value, see Password settings.

Request documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

User data of type Profile containing new password.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

Updated data of type Profile.

13.7.6. Search settings endpoint

Methods to work with personal search settings. This allows to store user settings between logins.

• Search settings DTO
Object attribute Description

userOid string

User oid to which these settings belong

settings Map<SearchSettingsType,string[]>

Current user’s search parameters. When user is doing search via POST /api/v4/terms/search last used parameters will be available in this property.
• SearchSettings type key

Enum key used by Search settings to store properties.

Object attribute Description

CLIENT_IDS

Not in use

DICTIONARY_IDS

An array of Dictionary ids used in current search

SECTION_OIDS

An array of Section oids used in current search

DOMAIN_OIDS

An array of Domain oids used in current search

QUICK_FILTER

Not in use

SEARCH_CASE_SENSITIVE

Not in use

SEARCH_FULL_TEXT

Not in use

SEARCH_MODE

Not in use

SEARCH_OPTIONS

Single element array containing next JSON object SearchOptions:

Property

Description

clear

true when clear search text on language change

normalized

When set to true characters with the same function but stored differently, as single-byte or double-byte characters, will be considered equal during filtering and term list sorting. If the option is selected, the normalized value will be used in filter criteria and thus filters can return results for both single-byte and double-byte characters.

fuzzy

true when search should include fuzzy matches

onlyDuplicates

true when search is looking only for duplicate terms

multiEnabled

true when multi-field search is enabled.

multiAllFields

true when multi-field search is looking for match in all fields.

fields

Map of Concept and Term Field oids Map<FieldLevel,string[]> to look when multi-field search is enabled

SELECTED_FILTER_ID

Single element array containing Filter id used in current search, or empty array

TERMLIST_LANG

Single element array containing Language code3 used as source language

SEARCH_TEXT

Single element array containing search text

TERMLIST_LANG2

Not in use

SELECTED_TERM

If user opened any term or terms, here will be an array of selected objects which kept open, with next properties:

Property

Description

termId

Term id of opened term

conceptId

Concept id of opened term

selectedTermId

<optional> will be only in one element pointing to currently active term

If user is using side-by-side view, array of selected objects will be two-dimensional

UI_SETTINGS

UI client can store here any configuration as an array of strings. Server will process here nothing.
• Get user settings

GET /api/v4/user-search-settings/

Returns user search settings for requested user

Request documentation
Query parameters

user-id number

User id
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body SearchSettings

JSON object of Search settings.
• Update user settings

PUT /api/v4/user-search-settings/

Request documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body SearchSettings

Data of type Search settings to save.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Profile

Updated data of type Profile.
• Update single search setting

PUT /api/v4/profile/password

Updates only one setting.

Request documentation
Query parameters

user-id number

User id of which setting to update

setting enum

One of the names of attribute of type Search settings.

Payload

body string[]

An array of string values
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body SearchSettings

Updated data of type Search settings.

13.8. Grid View

13.8.1. Staging areas endpoint

Description

Staging areas places where users can prepare coming changes to concepts in drafts. Areas can be shared between users.

• Staging area DTO
Object attribute Description

name string

Area name.

draftsNumber number

Amount of drafts stored in this staging area.

groupId number

Group id to which this area is available. null when visibility is set to "Owner"

settings string

[Edit format] UI client’s settings of StagingArea of current user. If user never used this staging area, then this value is null.

lockedLanguages string[]

[Edit format] List of locked languages code3 in dictionary which are not allowed to edit to current user.

dictionaryPermissions DictionaryPermissions

[Edit format] Dictionary permissions of StagingArea’s owner (created.id) applied to Concept editing. When owner of StagingArea is sharing it, edit permissions of concept drafts is also shared with other group members. Publishing right is never shared, other users must have their own permission to update concept to be able to publish. See more about DictionaryPermissions.

viewHiddenFields string[]

[Edit format] List of hidden fields oid in dictionary which are not allowed to show current user.

dictionaryId number

Dictionary id to which staging area related.

clientId number

Client id to which object belongs

id number

Staging area id.

version number

Staging area version number. Represents latest modification counter.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Update settings

PUT /api/v4/staging/{areaId}/settings

Description

Saves staging area UI settings for current user

Request documentation

Path parameters

areaId number

Staging area id where to save settings

Payload

body string

String containing configuration created by UI client. Server is not handling these values in any way.
Response documentation
Headers

Content-Type

application/json

Status

200 OK

In case of successfully processing request.
• Publish

POST /api/v4/staging/{areaId}/publish

Description

Starts publishing of Concept draft stored in specified area. All valid Concept drafts will be published and removed.

Request documentation

Path parameters

areaId number

Staging area id to publish
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful operation or 204 Accepted when operation is still in work.

Payload attributes InvocationResult

result boolean

true if publish of area is finished successfully.

jobTaskId number

When operation went to asynchronous execution, this value will have id of running job task. See JobTask.
• Merge

POST /api/v4/staging/{areaId}/merge

Description

Starts automatics merging of changes made in drafts and incoming updates from original Concepts.

Request documentation

Path parameters

areaId number

Staging area id to clear

Request parameters

mergeStrategy enum

Default value is AUTO. Possible values are:

  • AUTO try to merge changes automatically, when draft and concept have changes in same field, merge of this draft will be skipped

  • USE_YOURS ignore incoming changes from Concepts, keep all your changes in drafts.

  • USE_THEIRS ignore your changes in drafts, override everything with incoming changes from Concepts
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful result or 204 Accepted when operation is still in work.

Payload attributes InvocationResult

result boolean

true if clear of area is finished successfully.

jobTaskId number

When operation went to asynchronous execution, this value will have id of running job task. See JobTask.
• Clear

POST /api/v4/staging/{areaId}/clear

Description

Removes all concept drafts from staging area

Request documentation

Path parameters

areaId number

Staging area id to clear
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful result or 204 Accepted when operation is still in work.

Payload attributes InvocationResult

result boolean

true if clear of area is finished successfully.

jobTaskId number

When operation went to asynchronous execution, this value will have id of running job task. See JobTask.
• Find

GET /api/v4/staging/

Description

Finds staging areas with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter staging area objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters staging areas with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters staging areas with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content StagingArea[]

Found staging areas of type Staging area.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/staging/rownum/{id}

Description

Finds rownumber of staging area with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Staging area id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter staging area objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters staging areas with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters staging areas with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/staging/{id}

Description

Looks for staging area with specified id.

Request documentation

Path parameters

id number

Staging area id to look for

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body StagingArea

JSON object of Staging area.
• Create

POST /api/v4/staging/

Description

Creates new staging area from JSON data sent in payload.

Request documentation

Payload

body StagingArea

JSON object of type Staging area.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body StagingArea

Created object of staging area.
• Update

PUT /api/v4/staging/{id}

Description

Updates existing staging area from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Staging area which need to be updated

Payload

body StagingArea

JSON object of type Staging area. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body StagingArea

Updated staging area object.
• Partial update

PUT /api/v4/staging/partial/{id}

Description

It updates only specified parts of staging area from JSON data sent in payload. Unlike method PUT /api/v4/staging/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Staging area which need to be updated

Payload

body StagingArea

JSON object of type Staging area. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for staging area objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body StagingArea

Patched staging area object.
• Delete

DELETE /api/v4/staging/{id}

Description

Deletes staging area with specified id.

Request documentation

Path parameters

id number

Staging area id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/staging/async/{id[]}

Description

Deletes staging areas with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Staging area ids of staging areas to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is staging area id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.8.2. Concept drafts endpoint

Description

Concept drafts used to prepare new changes for actual Concepts. To make this data available draft must be published. When draft is deleted Concept remains untouched. But user can mark draft for deletion and publish that change and then concept will be deleted.

• Concept draft DTO
Object attribute Description

areaId number

Staging area id to which this draft belongs.

dictionaryId number

Dictionary id to which this concept draft is related

conceptDTO Concept

Current version of draft, represented as JSON object of type Concept.

originConceptDTO Concept

Original version of draft created from concept, represented as JSON object of type Concept.

metadataDTO ConceptDraftMetadataDto

Internal metadata records used mostly by workflows.

conceptChanged boolean

true when original Concept from which this draft has been created has incoming changes

permissions Map<ConceptPermission,boolean>

A map of Concept permissions of StagingArea owner. For current user this map will have one extra value with key DRAFT_PUBLISH. When user has permission to perform some operation, map will have value true.

termPermissions Map<string, Map<TermPermission,boolean>>

A map of term permissions for every Term in draft. Top level map consists of keys from Term tid, and value is map of Term permissions of StagingArea owner. When user has permission to perform some operation, map will have value true.

displayFields Map<string,DisplayField>

A map of Concept DisplayFields, key values is Field oid.

termDisplayFields Map<string, Map<string,DisplayField>>

A map of Term DisplayFields for every Term in draft. Top level map consists of keys from Term tid, and value is map of field oids and Display fields

comments Comment[]

An array of comments for this draft

sortValues any[]

An array of sort values which can be used as boundary id in POST /api/v4/concept-drafts/area/{area-id}/ method.

clientId number

Client id to which object belongs

id number

Concept draft id.

version number

Concept draft version number. Represents latest modification counter.

deleted number

true when object has been marked as deleted in database.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Create

POST /api/v4/concept-drafts/area/{area-id}/concept/

Description

Creates new ConceptDraft in specified Staging area.

Request documentation

Path parameters

area-id

Id of Staging area where to create new draft.

Payload

body

empty
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body ConceptDraft

Created object of Concept draft.
• Create from concepts

POST /api/v4/concept-drafts/area/{area-id}/concept/

Description

Creates new ConceptDraft in specified Staging area.

Request documentation

Path parameters

area-id

Id of Staging area where to create new draft.

Request parameters

concept-id

<optional> Id of Concept to create as draft

concept-oid

<optional> Oid of Concept to create as draft

Payload

body CreateParams

<optional> provide it when you want to create drafts from multiple Concepts.

Property Desc

conceptIds number[]

<optional> an array of Concept ids

conceptOids string[]

<optional> an array of Concept oids
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body ConceptDraft

Created object of Concept draft in case of single Concept.

In case of multiple concepts result will be different:

Payload attributes InvocationResult

result number

Amount of created concept drafts if operation finished successfully.

jobTaskId number

When operation went to asynchronous execution, this value will have id of running job task. See JobTask.

POST /api/v4/concept-drafts/area/{area-id}/concepts

Description

Creates new ConceptDraft in specified Staging area from search results.

Request documentation

Path parameters

area-id

Id of Staging area where to create new drafts.

Payload

body TermSearchRequest

Search request of type [doc-term-search-request]
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload attributes InvocationResult

result number

Amount of created concept drafts if operation finished successfully.

jobTaskId number

When operation went to asynchronous execution, this value will have id of running job task. See JobTask.
• Add term

POST /api/v4/concept-drafts/area/new-term/

Description

Adds new Term in specified ConceptDraft.

Request documentation

Request parameters

draft-id

Id of Concept draft where to create new term.

lang-code

code3 of Language in which add new term

Payload

body

empty
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload attributes NewTermResponse

draft ConceptDraft

Update object of Concept draft with new Term.

term Term

Created object of Term.
• Update bulk

POST /api/v4/concept-drafts/area/{area-id}/bulk-update/

Description

Bulk update of all fields in staging area

Request documentation

Path parameters

area-id number

Id of Staging area where to update field values.

Request parameters

field-oid string

Oid of Field to update

lang-code string

code3 of Language in which add new term

values string[]

Single element array with value to set, in case of multivalued picklist more than one string element.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload attributes InvocationResult

result BulkUpdateResults

updatedCount number

Amount of updated concept drafts

conflicts number[]

In case of conflicts during update an array of Concept draft ids which wasn’t updated

jobTaskId number

When operation went to asynchronous execution, this value will have id of running job task. See JobTask.
• Merge

PUT /api/v4/concept-drafts/merge/{id}

• Publish

PUT /api/v4/concept-drafts/publish/

• Changed concepts

GET /api/v4/concept-drafts/area/{area-id}/concepts-changed

Description

Checks amount of incoming concept changes available to drafts stored in specified staging area.

Request documentation

Path parameters

area-id number

Id of Staging area where to update field values.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Amount of incoming changes. 0 when no changes.
• Find

POST /api/v4/concept-drafts/area/{area-id}/

Description

Search for a concept drafts in Staging area

Request documentation

Path parameters

area-id

Id of Staging area where to create new drafts.

Payload attributes DraftsSearchRequest

dictionaryId number

Id of Dictionary related to StagingArea. Rudimentary attribute.

searchAfter any[]

An array of sort values which is used as boundary id after which next results will be returned. More traditionally it will be like offset in normal search.

sort SearchSort

langCode

code3 of Language in case of sorting by Term level field.

ascending

true if results should be sorted in ascending order

fieldOid

Field oid to sort by

fieldLevel

Field level value: CONCEPT or TERM

term string

Search string to look for matching term names

languages string[]

An array of code3 values of languages in which we’re looking for matching terms

pageSize number

amount of results to return.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload attributes InvocationResult

result number

Amount of created concept drafts if operation finished successfully.

jobTaskId number

When operation went to asynchronous execution, this value will have id of running job task. See JobTask.
• Get

GET /api/v4/concept-drafts/{id}

Description

Looks for concept draft with specified id.

Request documentation

Path parameters

id number

Concept draft id to look for

format enum

<optional>, default is 'FULL'
Response format for concept draft objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body ConceptDraft

JSON object of Concept draft.
• Update

PUT /api/v4/concept-drafts/{id}

Description

Updates existing concept draft from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Concept draft which need to be updated

Payload

body ConceptDraft

JSON object of type Concept draft. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for concept draft objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body ConceptDraft

Updated concept draft object.
• Delete

DELETE /api/v4/concept-drafts/{id}

Description

Deletes concept draft with specified id.

Request documentation

Path parameters

id number

Concept draft id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/concept-drafts/async/{id[]}

Description

Deletes concept drafts with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Concept draft ids of concept drafts to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is concept draft id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.9. Automation

13.9.1. Workflows endpoint

Description

Client administrator or dictionary administrator should be able to create/edit workflow for Dictionary.

With the workflow functionality in TermWeb you can define and automate tasks, control access permissions on the field level, and add styling to your term data, e.g. depending on term type or acceptability.

A workflow is connected to a task in TermWeb, e.g. creating a concept or deleting a term. When the task is performed, the associated workflows are executed. For a full list of available tasks, see Workflow tasks.

In a workflow you can define conditions, functions and validations to control what should happen when and where.

• Conditions

Conditions provides more detailed control over when the workflow should be executed. You can add conditions for field values in a concept or term, and also check user group membership for the user performing the task that triggered the workflow. For instance, you can define a workflow only to be executed when the concept has status "Pending" and user is a member of the group "Translators". For more information about defining conditions, see Editing Workflows

• Functions

A workflow function defines some action that should be performed when the workflow is executed. For instance, you can set field values in the concept or term, hide fields or make them read-only when editing, or change the field style (color, font style etc). You can define the functions to be executed before or after the workflow’s task. The functions to be executed before the task are defined as prefunctions in the workflow. The functions that should be executed when the task finishes are defined as postfunctions. For details about when pre- and postfunctions are executed for each task, see Workflow tasks.

• Validations

By adding validations to a workflow, you can define that some fields in the concept or term are required to have a value before saving, besides the fields already defined to be required in the dictionary definition. Using validations you can, for instance, require Definition to have a value if Status is set to Approved. Validations are only performed when saving after an editing task. For more information about validations see Validations under Editing Workflow Details below.

• Workflow tasks

The following table lists the available workflow tasks and when pre- and postfunctions are executed

Task

Prefunctions run when

Postfunctions run when

Create Concept

User is opening the Edit screen for a new concept entry

The concept is saved

Edit Concept

User is opening a concept entry for editing
or
The concept entry is added to the Staging area

The concept is saved

Delete Concept

User is selecting a concept entry for deletion

After the concept is deleted from the database

Add Term

User clicks "Add term" when editing a concept entry
or
User clicks "Add term" in the Staging area

User clicks "Save" in Concept editor
or
Or user publishes Concept changes in Staging area

Create Term

A new concept entry is saved (for each term entry)
or
A concept entry is saved after editing (for each new term entry)

Directly after prefunctions

Edit Term

User clicks "Edit term" on a term entry already stored in database when editing a concept entry

User clicks "Save" in Concept editor

Never called when editing in the Staging area

Update Term

User clicks "Save" in Concept editor. A modified term entry already stored in database will trigger function

Directly after prefunctions

Delete Term

User clicks "Save" in Concept editor. A deleted term entry stored in database will trigger function
or
A concept entry is deleted (for each term entry)

Directly after prefunctions

View Term in List

A term is displayed in the term list

Directly after prefunctions

View Concept

A concept entry is displayed in the concept window

Directly after prefunctions

View Term

A term entry is displayed (collapsed or expanded) in the result window

Directly after prefunctions

Select Term when Editing

Only supported in TermWeb 3

Only supported in TermWeb 3

Import Term Data

An import is started

When the imported is completed, but not if the import is cancelled by the user
Editing workflow details

To specify what actions should be performed by a workflow you click on workflow name in the workflow list page. The "Edit Workflow Details" view opens.

• Editing conditions

The conditions in a workflow determine when the workflow is executed. You can define a logical statement based on values in fields or the user’s group. Conditions can be specified right after selecting workflow task.

Only picklist fields can normally be used in workflow conditions. From version 3.12, also "Created by" and "Changed by" fields can be used in conditions, as well as values in normal text fields. For "Created by" and "Changed by", EQUALS and NOT EQUALS can be used, and login names should be used. For values in normal text fields, the EQUALS, NOT EQUALS, CONTAINS, AND NOT CONTAINS operators can be used. The selected field values should match the values in the entry being displayed or edited for the workflow to run. However, if one of the Edit Concept and Update Term tasks is selected (alone), a change of the contents of any field can be set to trigger a workflow email. For this to happen, select the Field changed condition.

If the workflow task affects a concept, e.g. Edit Concept or View Concept, and you have defined term level fields in the workflow conditions, all terms in the concept must fulfill the term level conditions. If the task affects a term, e.g. Edit Term or View Term in List, only the selected term and its concept must fulfill the conditions.

• Editing functions

Workflow functions are actions that the workflow performs when executed. They are divided into Prefunctions and Postfunctions, where the prefunctions are executed at the beginning of the workflow’s task, and the postfunctions are executed at the end. See Workflow tasks above for a full description.

• Function types

The following workflow function types are available:

  • Set Field Value
    Sets the value for a field in the current entry.

  • Render Field
    Changes how a field in the current entry is rendered, e.g. hidden or read-only.

  • Style Field
    Changes the appearance of a field in the current entry, e.g. color or size.

  • Send Email
    Sends a customizable email to a single user or one or more groups of users. Emails can be sent directly or collected in a digest sent on a regular interval or when the initiating task has been performed a certain number of times.

  • Send Reminder Email
    Sends a customizable email to a single user or group of users with delay. Delay value may use hours or days as time units. See details in the Procedural tips section.

  • Set Permission Scheme
    Temporarily changes the permission scheme for the user for the duration of the task.

  • Sort Terms
    Sorts the terms in a concept when displayed in the result window, based on a specific field value in the term.

Not all functions are applicable for all tasks, or as pre- or postfunctions. Only applicable functions are listed in the Add Function screen.

• Editing validations

Validations allow you to specify fields that should be required during an editing operation, besides the fields already defined as required in the dictionary definition. The workflow validations are checked when the entry is saved, and if a required value is missing the user will be informed and not able to save until a value is entered in the required field.

Sorting workflows in execution order in workflow list

To specify in which order the workflows of a certain dictionary are executed, you need to set sortIndex workflow’s attribute: This means that the workflow with the highest number or empty value will be executed last, that is; take priority over the workflows with lower numbers if in conflict.

• Workflow DTO
Object attribute Description

name string

Workflow name

description string

Description text

active boolean

true when workflow activated and working

sortIndex number

Index is used to order workflow’s execution. Workflow with the highest number or empty value will be executed last.

tasks enum[]

An array of tasks configured for workflow.
Possible values are:

  • com.nescit.term.workflow.task.CreateConceptTask

  • com.nescit.term.workflow.task.EditConceptTask

  • com.nescit.term.workflow.task.DeleteConceptTask

  • com.nescit.term.workflow.task.AddTermTask

  • com.nescit.term.workflow.task.CreateTermTask

  • com.nescit.term.workflow.task.EditTermTask

  • com.nescit.term.workflow.task.UpdateTermTask

  • com.nescit.term.workflow.task.DeleteTermTask

  • com.nescit.term.workflow.task.DisplayTermInListTask

  • com.nescit.term.workflow.task.DisplayConceptTask

  • com.nescit.term.workflow.task.DisplayTermTask

  • com.nescit.term.workflow.task.SelectTermTask

  • com.nescit.term.workflow.task.ImportTask

See Workflow tasks for more details

projectLevel boolean

true when workflow is stored in Project.

targetLangCodes string[]

List of code3 of Language used by Project workflow as trigger condition instead of tasks

conditions WorkflowCondition[]

An array of workflow conditions will be checked against updated Concept and its Terms or current User.

prefunctionCalls WorkflowFunctionCall[]

An array of prefunction calls which will be launched after checking conditions

postfunctionCalls WorkflowFunctionCall[]

An array of postfunction calls which will be launched after checking conditions

validations WorkflowValidation[]

An array of workflow validations will be checked against updated Concept and its Terms. In case of invalid Concept or Term execution of postfunctionCalls will be interrupted.

dictionaryId number

Dictionary id to which workflow related.

clientId number

Client id to which object belongs

id number

Workflow id.

oid string

Workflow oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• WorkflowCondition DTO
Object attribute Description

workflowConditionType enum

Condition type, specifies what data will be checked. Possible values are:

  • GROUP – current user belongs to specified group in value. Group oid should be stored in value.

  • FIELD – Field value is equal to specified value

  • FIELD_CHANGE – Field value has been changed. Field oid is stored in value

level enum

In case of workflowConditionType is equal to FIELD or FIELD_CHANGE specify here field level: CONCEPT or TERM

keyOid string

In case of workflowConditionType is equal to FIELD specify here Field oid, for FIELD_CHANGE keyOid will be FIELD_CHANGE, and for GROUP – GROUP

value string

Value to check against specified condition type, field value, modified fields or current user groups.

workflowLogicalOperator enum

Logical operator between to workflow conditions in a group. Possible values are: NO_OPERATOR, AND, OR

workflowComparisonOperator enum

Comparison operation to run against field value. Possible values for workflowConditionType = GROUP are: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS.
Possible values for workflowConditionType = FIELD are: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, EMPTY and NOT_EMPTY
For FIELD_CHANGE condition these comparisons not in use.

groupStart boolean

true when condition first in the sequence

groupEnd boolean

true when condition last in the sequence
• WorkflowFunctionCall DTO
Object attribute Description

workflowFunction enum

Function to invoke. Possible values are: ReminderEmail, SendEmail, RenderField, SetFieldValue, SetPermissionScheme, SortTerm or StyleField.

functionIndex number

Order number of function call

parameterMap Map<string, string>

Parameters for function invocation:

  • ReminderEmail

    • unit.type: 0 - Hour, 1 - Day

    • cond.type: 0 - Fulfilled, 1 - Not fulfilled

    • delay

    • conditions

    • rcpt.type: 0 - Group, 1 - Address, 2 - Language group

    • project.oid, clientoid, groupoids, email, subject, msg.text, wflow.oid, wflow.name, digest.enabled, digest.id, digest.type, digest.schedule.value, digest.number, digest.task.ids

  • SendEmail

    • content.type: 0 - Text, 1 - HTML

    • email.body, digest.displayed.langs, digest.term.fields, digest.concept.fields

    • rcpt.type: 0 - Group, 1 - Address, 2 - Language group

    • project.oid, clientoid, groupoids, email, subject, msg.text, wflow.oid, wflow.name digest.enabled, digest.id, digest.type, digest.schedule.value, digest.number, digest.task.ids

  • RenderField

    • value: VISIBLE, READONLY, HIDDEN

    • fieldoid

  • SetFieldValue

    • value, fieldoid

  • SetPermissionScheme

  • SortTerm

    • sort.increasing boolean

    • sort.within.language boolean

    • fieldoid

  • StyleField

    • css.color string

    • css.font-size string

    • css.font-weight string

    • css.font-style string

    • css.text-decoration string

    • fieldoid
• WorkflowValidation DTO
Object attribute Description

level enum

Field level: CONCEPT or TERM

fieldOid string

oid of Field to validate

valueRequired boolean

true if field value must be filled before saving Concept or Term
• Copy

POST /api/v4/workflows/copy-workflow

Description

Create a copy of workflow. It preserves new oid for copy of Workflow, but it is not saved yet to DB.

Request documentation

Request parameters

workflow-id number

Workflow id to copy

copy-name boolean

Keep original name from source workflow, or generate new unique one
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Workflow

A json object of type Workflow with copy of source workflow
• Find

GET /api/v4/workflows/

Description

Finds workflows with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter workflow objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters workflows with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters workflows with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Workflow[]

Found workflows of type Workflow.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/workflows/rownum/{id}

Description

Finds rownumber of workflow with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Workflow id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter workflow objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters workflows with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters workflows with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/workflows/{id}

Description

Looks for workflow with specified id.

Request documentation

Path parameters

id number

Workflow id to look for

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Workflow

JSON object of Workflow.
• Create

POST /api/v4/workflows/

Description

Creates new workflow from JSON data sent in payload.

Request documentation

Payload

body Workflow

JSON object of type Workflow.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Workflow

Created object of workflow.
• Update

PUT /api/v4/workflows/{id}

Description

Updates existing workflow from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Workflow which need to be updated

Payload

body Workflow

JSON object of type Workflow. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Workflow

Updated workflow object.
• Partial update

PUT /api/v4/workflows/partial/{id}

Description

It updates only specified parts of workflow from JSON data sent in payload. Unlike method PUT /api/v4/workflows/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Workflow which need to be updated

Payload

body Workflow

JSON object of type Workflow. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for workflow objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Workflow

Patched workflow object.
• Delete

DELETE /api/v4/workflows/{id}

Description

Deletes workflow with specified id.

Request documentation

Path parameters

id number

Workflow id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/workflows/async/{id[]}

Description

Deletes workflows with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Workflow ids of workflows to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is workflow id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.9.2. Projects endpoint

Description

Projects are used to group several workflows by one filter criteria to ease up administration

• Project DTO
Object attribute Description

name string

Project name.

description string

Description text

active boolean

true when workflow activated and working

variables Map<string, string>

A map of variables defined in project and can be used by workflows

filter Filter

Filter used by this project

workflows Workflow[]

Workflow workflows create in project

dictionaryId number

Dictionary id to which project related.

clientId number

Client id to which object belongs

id number

Project id.

oid string

Project oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• Find

GET /api/v4/projects/

Description

Finds projects with specified query parameters available to current user.

Request documentation

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter project objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters projects with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters projects with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content Project[]

Found projects of type Project.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/projects/rownum/{id}

Description

Finds rownumber of project with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

Project id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

dictionary-id number

<optional>, default is null.
Provide an id when you need to filter project objects related to specific dictionary.

client_id number

<optional>, default is equal to current client id related to authentication token.
[TIP] Reserved for future releases and can be omitted for now.

name string

<optional>, default is null
Filters projects with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters projects with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/projects/{id}

Description

Looks for project with specified id.

Request documentation

Path parameters

id number

Project id to look for

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body Project

JSON object of Project.
• Create

POST /api/v4/projects/

Description

Creates new project from JSON data sent in payload.

Request documentation

Payload

body Project

JSON object of type Project.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Project

Created object of project.
• Update

PUT /api/v4/projects/{id}

Description

Updates existing project from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of Project which need to be updated

Payload

body Project

JSON object of type Project. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Project

Updated project object.
• Partial update

PUT /api/v4/projects/partial/{id}

Description

It updates only specified parts of project from JSON data sent in payload. Unlike method PUT /api/v4/projects/{id}, patch will only update values of object which are present in JSON without modifying other fields which are not present in JSON.

Request documentation

Path parameters

id number

Id of Project which need to be updated

Payload

body Project

JSON object of type Project. Value of id and oid attribute specified in payload will be ignored by server.
Missing attributes in JSON object will be omitted. Fields in JSON object with null will be cleared.
Don’t forget to include "version" attribute value.

format enum

<optional>, default is 'FULL'
Response format for project objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body Project

Patched project object.
• Delete

DELETE /api/v4/projects/{id}

Description

Deletes project with specified id.

Request documentation

Path parameters

id number

Project id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion
• Delete async

DELETE /api/v4/projects/async/{id[]}

Description

Deletes projects with specified ids.
This operation may run asynchronous when deletion takes more than 15 seconds. In that case server will return http status code 202 Accepted.

Request documentation

Path parameters

id number[]

Project ids of projects to delete
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Status

code number

200 OK in case of successful deletion or 204 Accepted when operation is still deleting.

Payload attributes InvocationResult

result Map<number,boolean>

When operation has completed successfully, this result will contain map with entries where key is project id and value is boolean flag indicating result of deletion.

jobTaskId number

When operation went to asynchronous deletion, this value will have id of running job task. See JobTask.

13.10. File repository endpoint

Description

File repository allows users to store and share files between multiple dictionaries.

• VirtualFile DTO
Object attribute Description

name string

VirtualFile name.

description string

Description of virtual file.

fileType string

VirtualFile extension of file used during upload.

mimeType string

VirtualFile mime type of file determined from extension stored in fileType.

size number

File size in bytes.

virusCheck enum

VirusCheck status enum. Possible values are: NOT_SCANNED, SCANNING, OK, FAILED or INFECTED.

virusCheckMessage string

In case of failed scan or virus this will have information about it.

virusCheckAttempt number

Serial number of virus check attempt.

virusCheckLastAttempt number

Last time of virus check in milliseconds since Unix Epoch.

clientId number

Client id to which object belongs

id number

VirtualFile id.

oid string

VirtualFile oid. This is object id from old objects.

created Object

Metadata object containing information about creation

created.id number

User id created that object

created.name string

User login created that object

created.fullName string

User full name created that object

created.time number

Created date and time in milliseconds since Unix Epoch

created.oid string

User oid created that object (provided for backward compatibility)

changed Object

Metadata object containing information about last modification

changed.id number

User id changed that object

changed.name string

User login changed that object

changed.fullName string

User full name changed that object

changed.time number

Last change date and time in milliseconds since Unix Epoch

changed.oid string

User oid changed that object (provided for backward compatibility)
• FileRepositoryTasks
Object attribute Description

exportStatus ExportFileRepositoryTask

Current status of running export task described with ExportFileRepositoryTask. null when no running export task launched by current user.

importStatus ImportFileRepositoryTask

Current status of running import task described with ImportFileRepositoryTask. null when no running import task launched by current user.
• ImportFileRepositoryTask DTO
Object attribute Description

importedFiles number

Amount of files imported into repository

complete boolean

true when import task is finished successfully or with error.

error string

Error message if task has failed.

jobTask JobTask

Description of running TermWeb JobTask

progress number

Overall progress of task, values from 0 to 100.
• ExportFileRepositoryTask DTO
Object attribute Description

fileSize number

File size of export result.

complete boolean

true when export task is finished successfully or with error.

error string

Error message if task has failed.

progress number

Overall progress of task, values from 0 to 100.
• File data

GET /api/v4/files/{id}/data

Description

This operation retrieves a file contents from server.

Request documentation

Headers

X-Auth-token string

Authentication token can be sent for file retrieval as header or as cookie.

Path parameters

id number

VirtualFile id to look for.
Response documentation
Headers

Content-Type

VirtualFile.fileType

Content-Disposition

attachment; filename=“VirtualFile.name”

Content-Length

VirtualFile.size

Status

code number

200 OK in case of success.

Payload

body

File contents of file.
• Upload

POST /api/v4/files/upload

Description

This method allows to create a new VirtualFile or update existing one by uploading its contents.

Request documentation

Headers

Content-Type

multipart/form-data

Payload fields

file (binary)

Multipart data containing dictionary definition file.

file-id number

(Optional) provide VirtualFile.id when you need to update existing file.

file-name string

Name of uploaded file

file-description string

(Optional) Description for uploaded file
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body VirtualFile

JSON object of VirtualFile.
• File thumbnail

GET /api/v4/files/{id}/thumbnail

Description

This operation retrieves a file thumbnail contents from server if file image or video.

Request documentation

Headers

X-Auth-token string

Authentication token can be sent for file retrieval as header or as cookie.

Path parameters

id number

VirtualFile id to look for.

Request parameters

size string

<optional> pass origin string when you want to retrieve video thumbnail unchanged.
Response documentation

Status

code number

200 OK in case of success.
415 UNSUPPORTED_MEDIA_TYPE Thumbnails available only for video and image files.

Payload

body

Thumbnail contents of file.
• Upload video thumbnail

POST /api/v4/files/{id}/thumbnail

Description

This method allows to upload new or change current thumbnail for video file.

Request documentation

Headers

Content-Type

multipart/form-data

Path parameters

id number

VirtualFile id for which thumbnail will be uploaded.

Payload fields

thumbnail (binary)

Multipart data containing thumbnail file.
Response documentation

Status

code number

200 OK in case of success.

Payload

body

empty
• File repository tasks

GET /api/v4/files/tasks

Description

This operation retrieves current import/export tasks launched by current user.

Request documentation

Request parameters

none
Response documentation

Payload

body FileRepositoryTasks

JSON object of <<doc-dto-file-repository-tasks.
• Start file repository export

POST /api/v4/files/export-repo

Description

This operation starts asynchronous task of exporting all files from repository into zip file. You may check results by getting status from GET /api/v4/files/tasks or by checking

Request documentation

Request parameters

none
Response documentation

Status

code number

200 OK in case of success.
429 TOO_MANY_REQUESTS If current user already have running export file repository task.

Payload InvocationResult<boolean>

result boolean

When operation has completed immediately then this property will be equal to true

jobTaskId number

When operation went to asynchronous execution, this value will have id of running job task. See JobTask.
• Get export file repository result

GET /api/v4/files/export-repo/result

Description

This operation retrieves a file thumbnail contents from server if file image or video.

Request documentation

Request parameters

none
Response documentation

Headers

Content-Type

application/zip

Status

code number

200 OK in case of success.
404 NOT FOUND in case when there is no available export result.

Payload

body

Binary data of zip file with exported file repository.
• Clear export results

POST /api/v4/files/export-repo/finish

Description

This operation clears export repository results. If export task was finished.

Request documentation

Request parameters

none
Response documentation

Status

code number

200 OK in case of success.
409 CONFLICT If there is no actual export repository results.

Payload

body

empty
• Start file repository import

POST /api/v4/files/import-repo

Description

This method starts import of file repository archive from zip file. If file repository contains file with same name as file from archive, file in repository will be replaced with new contents from archive.

For every new file new VirtualFile wil be created.

Request documentation

Headers

Content-Type

multipart/form-data

Payload fields

file (binary)

Multipart data containing file repository archive.
Response documentation

Status

code number

200 OK in case of success.
429 TOO_MANY_REQUESTS If current user already have running import file repository task.

Payload InvocationResult<boolean>

result boolean

When operation has completed immediately then this property will be equal to true

jobTaskId number

When operation went to asynchronous execution, this value will have id of running job task. See JobTask.
• Clear import results

POST /api/v4/files/import-repo/finish

Description

This operation clears import repository results. If import task was finished.

Request documentation

Request parameters

none
Response documentation

Status

code number

200 OK in case of success.
409 CONFLICT If there is no actual import repository results.

Payload

body

empty
• Find

GET /api/v4/files/

Description

Finds virtual files with specified query parameters available to current user.

Request documentation

Query parameters

name string

<optional>, default is null
Filters virtual files with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters virtual files with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for virtual file objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.

size number

<optional>, default is 20
Page size, represents how many of objects can be returned

page number

<optional>, default is 0
Page number, represents from which position to start loading data, in other words offset equal to size * page.

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

content VirtualFile[]

Found virtual files of type VirtualFile.

last boolean

indicates if this page is last with current search params

totalElements number

total amount of objects accessible from this endpoint

totalPages number

total number of pages available with current page size and total elements

sort string

current sort params, like 'name,ASC'

numberOfElements number

amount of objects returned with this page

first boolean

indicates if this page is first with current search params

size number

current page size

number number

current page number
• Row number

GET /api/v4/files/rownum/{id}

Description

Finds rownumber of virtual file with specified filter and sort parameters. Useful when you need to determine page where object is located after creation or update.

Request documentation

Path parameters

id number

VirtualFile id to look for

sort string

<optional>, default is null
Order direction of returned data by some attribute, can accept most of object attributes for specific endpoint. For example: 'name', 'name,ASC', 'name,DESC'.

Query parameters

name string

<optional>, default is null
Filters virtual files with name starting with provided value. Search will be case insensitive.

name-eq string

<optional>, default is null
Filters virtual files with name equal to provided value ignoring case.

format enum

<optional>, default is 'FULL'
Response format for virtual file objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body number

Found row number for specified parameters, in case when nothing found return 0.
• Get

GET /api/v4/files/{id}

Description

Looks for virtual file with specified id.

Request documentation

Path parameters

id number

VirtualFile id to look for

format enum

<optional>, default is 'FULL'
Response format for virtual file objects, possible values are ID, SHORT, FULL, EDIT. See Formats.

include-deleted boolean

<optional>, default is false
When value is true TermWeb will include softly deleted objects to search results.
This function is available only to System or client administrators.
Response documentation

Headers

Content-Type

application/json;charset=UTF-8

Payload

body VirtualFile

JSON object of VirtualFile.
• Update

PUT /api/v4/files/{id}

Description

Updates existing virtual file from JSON data sent in payload.

Request documentation

Headers

Content-Type

application/json

Path parameters

id number

Id of VirtualFile which need to be updated

Payload

body VirtualFile

JSON object of type VirtualFile. Value of id and oid attribute specified in payload will be ignored by server.
Don’t forget to include "version" attribute value.
Missing attributes in JSON object or null values will erase that value on server side.

format enum

<optional>, default is 'FULL'
Response format for virtual file objects, possible values are ID, SHORT, FULL, EDIT. See Formats.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body VirtualFile

Updated virtual file object.
• Delete

DELETE /api/v4/files/{id}

Description

Deletes virtual file with specified id.

Request documentation

Path parameters

id number

VirtualFile id to delete
Response documentation
Headers

Content-Type

text/plain;charset=UTF-8

Status

code number

204 No Content in case of successful deletion

13.10.20. Feedback endpoint

Description

This endpoint is used for sending feedback from user when it enabled. You can check current status of feedback by using GET /api/v4/ui/feedback-page for current Client.

• Send

POST /api/v4/feedback

Description

If feedback is enabled email message will be sent to configured user.

Request documentation

Headers

Content-Type

multipart/form-data

Payload fields

name string

Name of the sender

email string

A valid email of a sender

subject string

Subject for feedback

dictionaryId number

<optional> Dictionary id in case message is related to specific. TermWeb will try to find responsible user for it.

message string

Message to send. Maximum

attachment (binary)

Multipart data containing attachment file. Maximum accepted file size can be found in Response documentation.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body

Empty

13.11. BIMA endpoint

Description

This endpoint describes the configuration for TermWeb Business Integration Message Adapter (BIMA).

BIMA allows to consumers subscribe to messages from TermWeb via Java Messaging System (JMS) or Kafka streams.

There are two TermWeb operations that causes BIMA to generate messages; initial transfer (export of term database) and update of term data. When such an operation occurs, BIMA generates one or more messages and publishes them to the message broker’s publish/subscribe topics defined in BIMA’s configuration file.

• BIMA configuration DTO
Object attribute Description

adapterEnabled boolean

true when adapter is enabled

commonProps Map<string,string>

Map of common properties for adapter stored in BimaAdapter.properties file

jmsEnabled boolean

true when JMS is enabled

jmsInitError string

Contains error message of JMS initialization if it occurred during startup or in enable method.

jmsProps Map<string,string>

Map of JMS properties for adapter stored in BimaAdapter.properties file (all properties starting with jms. prefix)

kafkaEnabled boolean

true when Kafka client is enabled

kafkaInitError string

Contains error message of Kafka client initialization if it occurred during startup or in enable method.

kafkaProps Map<string,string>

Map of Kafka client properties for adapter stored in BimaAdapter.properties file (all properties starting with kafka. prefix)
• BIMA export data DTO
Object attribute Description

exportSettingsId number

Id of selected Export settings. Can’t be null.

messageBroker enum

true when adapter is enabled
Possible values are: JMS, KAFKA. Can’t be null.

topicName string

Topic name which will be used for publishing messages of initial transfer. Can’t be empty.

running boolean

true when initial transfer is running.

conceptsProcessedCount number

Amount of concepts which has been sent to topic. Value is empty if transfer has never been launched.

preview BimaExportPreview

Returns information about data to be exported when exportSettingsId contains valid id. See BIMA export preview.

result BimaExportResult

When transfer is launched this property will be not null and contain information about progress and result. See BIMA export result.
• BIMA export preview DTO
Object attribute Description

dictionaryId number

Id of Dictionary from which transfer will be executed.

filterId number

Id of Filter used by export settings specified in BIMA export data. Can be null.

filterName string

Name of Filter used by export settings specified in BIMA export data. Can be null;

selectedLanguages string[]

An array of Language codes (code3) selected to be included in export. Not null.

selectedConceptFields string[]

An array of concept level Field oids selected to be included in export. Not null.

selectedTermFields string[]

An array of term level Field oids selected to be included in export. Not null.

conceptsCount number

Amount of concepts which will be exported.
• BIMA export result DTO
Object attribute Description

successfullyExportedConcepts number

Number of successfully exported concepts.

failedConcepts number

Number of concepts failed to export. Can be null.

startTime number

Export start date and time in milliseconds since Unix Epoch

completeTime number

Export finishA date and time in milliseconds since Unix Epoch

elapsedTime string

Elapsed time since export start in human-readable format

estimatedTotalTime string

Estimated total time since export start in human-readable format

errorMsg string

Error message if export finished with error

cancelled boolean

true if export has been cancelled by user
• BIMA config

GET /api/v4/bima/config

Description

This operation retrieves a current BIMA configuration from server.

Request documentation

Path parameters

no parameters
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body BimaConfig

Response of type BIMA configuration.
• BIMA enable

POST /api/v4/bima/enable

Description

This operation enables adapter or one of the publishers (JMS, Kafka).

Request documentation
Request body EnableRequest

enableAdapter boolean

true when you need to enable BIMA, null or empty when you don’t want change status of adapter

enableJms boolean

true when you need to enable JMS publisher, null or empty when you don’t want change status of publisher

enableKafka boolean

true when you need to enable Kafka publisher, null or empty when you don’t want change status of publisher
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body BimaConfig

Updated configuration described with type BIMA configuration.
• BIMA disable

POST /api/v4/bima/disable

Description

This operation disables adapter or one of the publishers (JMS, Kafka).

Request documentation
Request body DisableRequest

disableAdapter boolean

true when you need to disable BIMA, null or empty when you don’t want change status of adapter

disableJms boolean

true when you need to disable JMS publisher, null or empty when you don’t want change status of publisher

disableKafka boolean

true when you need to disable Kafka publisher, null or empty when you don’t want change status of publisher
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body BimaConfig

Updated configuration described with type BIMA configuration.
• Set BIMA export data

POST /api/v4/bima/data/

Description

Sets initial configuration for initial transfer. This method can be invoked only when export data has not been set and transfer is not running for current user.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token

Payload

body BimaExportData

JSON object of type BIMA export data with all required properties entered.
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body BimaExportData

JSON object of BIMA export data with filled preview property in case of success.
• Get BIMA export data

GET /api/v4/bima/data

Description

Returns current configuration and status of Initial transfer.

Request documentation
Headers

X-Auth-Token

Unexpired authentication token
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body BimaExportData

JSON object of BIMA export data if it was set or launched otherwise empty body is returned.
• BIMA start export

POST /api/v4/bima/start

Description

This operation starts export which been properly configured via POST /api/v4/bima/data/

Request documentation
Payload

body

empty
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body BimaExportData

Initial result of invocation described with type BIMA export data.
• BIMA stop export

POST /api/v4/bima/stop

Description

This operation stops currently running export which been launched via POST /api/v4/bima/start

Request documentation
Payload

body

empty
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body

empty
• BIMA clear export data

POST /api/v4/bima/clear

Description

This operation clears current results or configuration set for current user.

Request documentation
Payload

body

empty
Response documentation
Headers

Content-Type

application/json;charset=UTF-8

Payload

body

empty

14. API methods Index

Authentication

POST /api/v4/login
POST /api/v4/logout
POST /api/v4/logout-user
GET /api/v4/validate
POST /api/v4/extend-sesion
POST /api/v4/switch-client
POST /api/v4/reset-password

Clients

GET /api/v4/clients/available
POST /api/v4/clients/generate-new-api-key/{client-id}
GET /api/v4/clients/
GET /api/v4/clients/rownum/{id}
GET /api/v4/clients/{id}
POST /api/v4/clients/
PUT /api/v4/clients/{id}
PUT /api/v4/clients/partial/{id}
DELETE /api/v4/clients/{id}
DELETE /api/v4/clients/async/{id[]}

API synchronization settings

GET /api/v4/sync-settings/
GET /api/v4/sync-settings/rownum/{id}
GET /api/v4/sync-settings/{id}
POST /api/v4/sync-settings/
PUT /api/v4/sync-settings/{id}
PUT /api/v4/sync-settings/partial/{id}
DELETE /api/v4/sync-settings/{id}
DELETE /api/v4/sync-settings/async/{id[]}

API templates

GET /api/v4/api-templates/defaults
GET /api/v4/api-templates/
GET /api/v4/api-templates/rownum/{id}
GET /api/v4/api-templates/{id}
POST /api/v4/api-templates/
PUT /api/v4/api-templates/{id}
PUT /api/v4/api-templates/partial/{id}
DELETE /api/v4/api-templates/{id}
DELETE /api/v4/api-templates/async/{id[]}

Job tasks

GET /api/v4/jobtasks/active
GET /api/v4/jobtasks/results/{id}
GET /api/v4/jobtasks/status/{id}

License

GET /api/v4/system/license
POST /api/v4/system/license

Features

GET /api/v4/system/features
GET /api/v4/system/features.js

Users

POST /api/v4/users/import/
GET /api/v4/users/export/
PUT /api/v4/users/assign-clients/
GET /api/v4/users/password-settings/
GET /api/v4/users/guest/
PUT /api/v4/users/guest/
GET /api/v4/users/
GET /api/v4/users/rownum/{id}
GET /api/v4/users/{id}
POST /api/v4/users/
PUT /api/v4/users/{id}
PUT /api/v4/users/partial/{id}
DELETE /api/v4/users/{id}
DELETE /api/v4/users/async/{id[]}

Groups

GET /api/v4/groups/
GET /api/v4/groups/rownum/{id}
GET /api/v4/groups/{id}
POST /api/v4/groups/
PUT /api/v4/groups/{id}
PUT /api/v4/groups/partial/{id}
DELETE /api/v4/groups/{id}
DELETE /api/v4/groups/async/{id[]}

Permissions

GET /api/v4/access/dictionary-permissions

Dictionaries

GET /api/v4/dictionaries/data-categories
POST /api/v4/dictionaries/language-replace/
GET /api/v4/dictionaries/
GET /api/v4/dictionaries/rownum/{id}
GET /api/v4/dictionaries/{id}

Sections

POST /api/v4/sections/clear/
GET /api/v4/sections/
GET /api/v4/sections/rownum/{id}
GET /api/v4/sections/{id}
POST /api/v4/sections/
PUT /api/v4/sections/{id}
PUT /api/v4/sections/partial/{id}
DELETE /api/v4/sections/{id}
DELETE /api/v4/sections/async/{id[]}

Fields

GET /api/v4/fields/incremental/next/{field-oid}
GET /api/v4/fields/incremental/validate/{field-oid}
GET /api/v4/fields/generate-picklist/{field-oid}

Domains

GET /api/v4/domains/
GET /api/v4/domains/rownum/{id}
GET /api/v4/domains/{id}
POST /api/v4/domains/
PUT /api/v4/domains/{id}
PUT /api/v4/domains/partial/{id}
DELETE /api/v4/domains/{id}
DELETE /api/v4/domains/async/{id[]}

Filters

POST /api/v4/filters/index/{id}
GET /api/v4/filters/
GET /api/v4/filters/rownum/{id}
GET /api/v4/filters/{id}
POST /api/v4/filters/
PUT /api/v4/filters/{id}
PUT /api/v4/filters/partial/{id}
DELETE /api/v4/filters/{id}
DELETE /api/v4/filters/async/{id[]}

Views

GET /api/v4/views/
GET /api/v4/views/rownum/{id}
GET /api/v4/views/{id}
POST /api/v4/views/
PUT /api/v4/views/{id}
PUT /api/v4/views/partial/{id}
DELETE /api/v4/views/{id}
DELETE /api/v4/views/async/{id[]}

Export settings

GET /api/v4/export-settings/
GET /api/v4/export-settings/rownum/{id}
GET /api/v4/export-settings/{id}

Concepts

GET /api/v4/concepts/{id}
GET /api/v4/concepts/
POST /api/v4/concepts/
PUT /api/v4/concepts/{id}
DELETE /api/v4/concepts/{id}
GET /api/v4/concepts/{id}/print-as-html
GET /api/v4/concepts/{id}/permissions

Terms

POST /api/v4/terms/search
POST /api/v4/terms/suggestion
GET /api/v4/terms/duplicates

Display concepts

GET /api/v4/display-concepts/{id}
POST /api/v4/display-concepts/create/{dictionary-id}
PUT /api/v4/display-concepts/edit/{concept-id}
POST /api/v4/display-concepts/copy/{concept-id}
POST /api/v4/display-concepts/add-term/{concept-id}
POST /api/v4/display-concepts/copy/{concept-id}

Comments

GET /api/v4/comments/
POST /api/v4/comments/
DELETE /api/v4/comments/{id}

History

GET /api/v4/history/concept/{concept-id}
GET /api/v4/history/dictionary/{dictionary-id}
POST /api/v4/history/concept-undo/
POST /api/v4/history/dictionary-undo/

User Session data

GET /api/v4/data

User Profile

GET /api/v4/profile/
PUT /api/v4/profile/
PUT /api/v4/profile/password

UI Menu

GET /api/v4/ui/menu/top
GET /api/v4/ui/menu/side/{idx}

Feedback

POST /api/v4/feedback

Feedback page

GET /api/v4/ui/feedback-page
PUT /api/v4/ui/feedback-page

Welcome page

GET /api/v4/ui/welcome-page
PUT /api/v4/ui/welcome-page

User search settings

GET /api/v4/user-search-settings/
PUT /api/v4/user-search-settings/
PUT /api/v4/profile/user-search-settings/

Staging areas

PUT /api/v4/staging/{areaId}/settings
POST /api/v4/staging/{areaId}/clear
POST /api/v4/staging/{areaId}/merge
POST /api/v4/staging/{areaId}/publish
GET /api/v4/staging/
GET /api/v4/staging/rownum/{id}
GET /api/v4/staging/{id}
POST /api/v4/staging/
PUT /api/v4/staging/{id}
PUT /api/v4/staging/partial/{id}
DELETE /api/v4/staging/{id}
DELETE /api/v4/staging/async/{id[]}

Concept drafts

POST /api/v4/concept-drafts/area/{area-id}/concept/
POST /api/v4/concept-drafts/area/{area-id}/concept/
POST /api/v4/concept-drafts/area/{area-id}/concepts/
POST /api/v4/concept-drafts/area/new-term/
POST /api/v4/concept-drafts/area/{area-id}/bulk-update/
PUT /api/v4/concept-drafts/merge/{id}
PUT /api/v4/concept-drafts/publish/
GET /api/v4/concept-drafts/area/{area-id}/concepts-changed/
POST /api/v4/concept-drafts/area/{area-id}/
GET /api/v4/concept-drafts/{id}
PUT /api/v4/concept-drafts/{id}
DELETE /api/v4/concept-drafts/{id}
DELETE /api/v4/concept-drafts/async/{id[]}

Workflows

POST /api/v4/workflows/copy-workflow
GET /api/v4/workflows/
GET /api/v4/workflows/rownum/{id}
GET /api/v4/workflows/{id}
POST /api/v4/workflows/
PUT /api/v4/workflows/{id}
PUT /api/v4/workflows/partial/{id}
DELETE /api/v4/workflows/{id}
DELETE /api/v4/workflows/async/{id[]}

Projects

GET /api/v4/projects/
GET /api/v4/projects/rownum/{id}
GET /api/v4/projects/{id}
POST /api/v4/projects/
PUT /api/v4/projects/{id}
PUT /api/v4/projects/partial/{id}
DELETE /api/v4/projects/{id}
DELETE /api/v4/projects/async/{id[]}

Files

GET /api/v4/files/tasks
GET /api/v4/files/{id}/data
POST /api/v4/files/upload
GET /api/v4/files/{id}/thumbnail
POST /api/v4/files/{id}/thumbnail
POST /api/v4/files/export-repo
GET /api/v4/files/export-repo/result
POST /api/v4/files/export-repo/finish
POST /api/v4/files/import-repo
POST /api/v4/files/import-repo/finish
GET /api/v4/files/
GET /api/v4/files/rownum/{id}
GET /api/v4/files/{id}
PUT /api/v4/files/{id}
DELETE /api/v4/files/{id}

BIMA

GET /api/v4/bima/config
POST /api/v4/bima/enable
POST /api/v4/bima/disable
POST /api/v4/bima/data/
GET /api/v4/bima/data/
POST /api/v4/bima/start
POST /api/v4/bima/stop
POST /api/v4/bima/clear

15. DTO Index

APISyncSettings
APITemplate
APITemplateSettings
BIMA configuration
BIMA export data
BIMA export preview
BIMA export result
Client
Comment
Concept
Concept draft
Concept relation
DataCategory
Dictionary
DictionaryPermissions
Display concept
Display field
Display term
Domain
Export settings
Feedback page
Field
Field Model
ExportFileRepositoryTask
ImportFileRepositoryTask
FileRepositoryTasks
Filter
Filter criterion
Group
GuestSettings
History item
JobTask
Language
Language Variant
License
Menu item
NamedObject
OnlineUser
Permission scheme
Picklist item
Profile
Project
Role
RefLink
Search settings
Section
Session data
Staging area
Statistics
StatisticsSummary
StatisticsMonthSummary
StatisticsMonthDetails
Term
User
UserLogItem
User preferences
View
VirtualFile
Workflow
Workflow condition
Workflow function call
Workflow validation