Update a target
PUT/api/v2/workspace/:workspaceId/survey/:surveyCode/target/:elementId
Replaces the name and the TGL expression of an existing target.
This is a full replacement: send both label and tgl, even when only one of them changes. The new expression is checked against the variables of surveyCode before anything is saved: if the check fails, the target is left unchanged. The target keeps its id and its place in the workspace folders, so requests that reference it by id use the new definition.
Before you call it
workspaceId: the workspace that contains the target (see Shared workspaces below).elementId: the targetid, fromGET .../targets(nodes withtype: TARGET_VAR) or from the response ofPOST .../target.surveyCode: the survey used to check the expression, usually the workspace's ownsurveyCode.- Variable and category codes: the
idvalues returned byGET /api/v2/survey/{surveyCode}/variables. The accepted TGL is the same as forPOST .../target; see also the TGL guide.
Request body
| Field | Required | Description |
|---|---|---|
label | Yes | New name of the target. Cannot be empty. Also replaces its title and description. |
tgl | Yes | New boolean TGL expression. Cannot be empty. |
Unknown fields are ignored. To rename a target without changing its definition, send its current expression, available as filterTgl from POST .../targets/details. Part labels are not included in filterTgl, so a rename sent this way removes them.
Response
200 OK with the target id, and label and tgl exactly as you sent them.
Behaviour
- Idempotent: repeating the same request leaves the target in the same state; only its update date changes.
- No concurrency control: when two clients update the same target at the same time, the last request processed wins. There is no version check and no
409 Conflict. - Shared workspaces: only the workspace owner changes the target itself. In a workspace that is shared with you, the new expression is saved as your personal version of the target, which the owner and other users do not see, and the name does not change. Changes can take up to one hour to be visible to the other users of a shared workspace.
elementIdmust identify a target: the id of any other workspace element (a table, for example) is rejected withWS_ERR_102.- The expression is checked before the target is looked up, so an invalid expression returns a TGL error even when
elementIddoes not exist.
Errors
errorMessage is meant for people and may be in the user's language. Base your error handling on errorCode.
| Status | errorCode | When |
|---|---|---|
| 400 | VAL_ERR_001 | label or tgl is missing or empty, or the body is empty. |
| 400 | E400 | The body is not valid JSON. |
| 400 | AE_ERR_400 | The body is a JSON array, or a value has the wrong JSON type, such as an object in tgl. The message names the field. |
| 400 | TGL_ERR_101 | The expression references a variable or category that does not exist in surveyCode. |
| 400 | WS_ERR_102 | No target with this elementId exists in this workspace: unknown id, unknown workspace, or an element that is not a target. |
| 400 | WS_ERR_403 | The workspace belongs to another user and is not shared with you. |
| 400 | TW_ERR_500 | The X-API-Key value does not identify a TOM user. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 422 | TGL_INVALID | The expression cannot be parsed, or uses a variable without a category or a condition. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 422
- 500
The target was updated. Returns its id, and the label and tgl you sent.
The request cannot be processed. WS_ERR_102: no target with this elementId exists in this workspace. TGL_ERR_101: the expression references a variable or category that does not exist in surveyCode. WS_ERR_403: the workspace belongs to another user and is not shared with you. E400: the body is not valid JSON. AE_ERR_400: the body is a JSON array, or a value has the wrong JSON type. TW_ERR_500: the X-API-Key value does not identify a TOM user. VAL_ERR_001: label or tgl is missing or empty, or the body is empty.
The X-API-Key header is missing or empty.
The TGL expression cannot be used: it does not parse, or it uses a variable without a category or condition. An unknown variable or category returns 400 TGL_ERR_101 instead.
Unexpected error.