Query the custom tree of a workspace
POST/api/v2/workspace/:workspaceId/survey/:surveyCode/tree/query/custom
Queries, on demand, the custom elements of a workspace: the targets and user variables saved in it, organised in the workspace's folders.
It works like POST /api/v2/survey/{surveyCode}/tree/query, with the differences listed below. Use it to build pickers for user variables and targets, and to check that they can be used with a survey before putting them in a table.
Before you call it
workspaceIdis theidof a workspace returned byGET /api/v2/workspaces.surveyCodeis thecodeof a survey returned byGET /api/v2/users/surveys. It is used to check your access and to validate the elements against that survey's variables; it does not filter which elements are returned.
Tree structure
- Two root folders:
ROOT_FOLDER_TARGET(targets) andROOT_FOLDER_USER_VAR(user variables). Theiridandcodeare these fixed values, so you can expand them directly withNODE_CHILD; theirlabelis in the user's language. - Below them: folders (
FOLDER), targets (TARGET_VAR, subtypeLOGIC), user variables (CUSTOM_VAR) and, forSINGLEandMULTIPLEuser variables, their categories (CUSTOM_CAT). - For every custom node,
idandcodehold the same value: the element id. Put the id of aCUSTOM_VAR(with itssubtype) or of aTARGET_VARin aVARIABLESaxis ofPOST /api/v2/table/{surveyCode}.
Validation (status)
- With
validate=true(default) each user variable and target is checked against the variables ofsurveyCode. Elements that cannot be used with the survey at all are left out. Elements that can only be used in part are returned withstatus: INVALID, unlessexcludeInvalidistrue, which drops them too. The rest areVALID. statusisNOT_VALIDATEDwhenvalidate=false, when the request has atext, or when the result holds more elements than the server validates in one request.- Read
statusin flat mode only: withtreeMode=trueevery node reportsVALID. validInSourcesappears on user variables that can only be used with the surveys listed there.
Differences from the survey tree query
- Only the
VARIABLEStree has custom elements: a request whose only tree type isCARRIERSreturnsTREE_ERR_404. nodesIdholds element ids (or the root ids above).nodes,searchField,languageandexcludeCustomsare ignored.- The anchors in
nodesIdare left out of the result with every method, includingNODEandALL, unlessincludeSelectedistrue. To fetch given elements, sendNODEwithincludeSelected: true. NODE_FULL_HIERARCHYis not supported.NODE_CHILDandNODE_HIERARCHYrequirenodesId: without it, or with an empty list, the request is rejected with400(AE_ERR_400).NODE_PARENTShas no depth limit.- The whole result is always returned: there is no
206.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | TREE_ERR_404 | No element matches the query, or the workspace does not exist, or the request uses NODE_FULL_HIERARCHY, CARRIERS as the only tree type, or NODE with nodesId and without includeSelected. |
| 400 | AE_ERR_400 | method is present but has no type. |
| 400 | AE_ERR_400 | NODE_CHILD or NODE_HIERARCHY without nodesId, or with an empty one. |
| 400 | AE_ERR_400 | treeType is an empty list. |
| 400 | AE_ERR_412 | treeType has a null item; the message gives its position. |
| 400 | validation error | method or treeType is missing. |
| 400 | E400 | The body is not valid JSON. |
| 400 | AE_ERR_401 | method.type, treeType, types or searchField has an unknown value, or a number instead of a name. The message names the field, with its position in a list, and lists the valid values. Values are case-sensitive. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 403 | AE_ERR_415 | The survey is not available to you. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 403
- 500
The custom nodes that match the query: a flat array sorted by order, or a nested array when treeMode=true.
The request cannot be answered. TREE_ERR_404: no element matches the query, the workspace does not exist, or the request uses an unsupported combination (see the operation description). AE_ERR_400: method has no type, NODE_CHILD or NODE_HIERARCHY has no nodesId, or treeType is empty. AE_ERR_412: treeType has a null item. E400: the body is not valid JSON. AE_ERR_401: an enumerated field (method.type, treeType, types or searchField) has an unknown value; the message lists the valid ones. A missing method or treeType is also answered with 400.
The X-API-Key header is missing or empty.
The survey is not available to the user: not contracted, disabled, being loaded or non-existent. The answer is the same in every case (AE_ERR_415).
Unexpected error.