Skip to main content

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​

  • workspaceId is the id of a workspace returned by GET /api/v2/workspaces.
  • surveyCode is the code of a survey returned by GET /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) and ROOT_FOLDER_USER_VAR (user variables). Their id and code are these fixed values, so you can expand them directly with NODE_CHILD; their label is in the user's language.
  • Below them: folders (FOLDER), targets (TARGET_VAR, subtype LOGIC), user variables (CUSTOM_VAR) and, for SINGLE and MULTIPLE user variables, their categories (CUSTOM_CAT).
  • For every custom node, id and code hold the same value: the element id. Put the id of a CUSTOM_VAR (with its subtype) or of a TARGET_VAR in a VARIABLES axis of POST /api/v2/table/{surveyCode}.

Validation (status)​

  • With validate=true (default) each user variable and target is checked against the variables of surveyCode. Elements that cannot be used with the survey at all are left out. Elements that can only be used in part are returned with status: INVALID, unless excludeInvalid is true, which drops them too. The rest are VALID.
  • status is NOT_VALIDATED when validate=false, when the request has a text, or when the result holds more elements than the server validates in one request.
  • Read status in flat mode only: with treeMode=true every node reports VALID.
  • validInSources appears on user variables that can only be used with the surveys listed there.

Differences from the survey tree query​

  • Only the VARIABLES tree has custom elements: a request whose only tree type is CARRIERS returns TREE_ERR_404.
  • nodesId holds element ids (or the root ids above). nodes, searchField, language and excludeCustoms are ignored.
  • The anchors in nodesId are left out of the result with every method, including NODE and ALL, unless includeSelected is true. To fetch given elements, send NODE with includeSelected: true.
  • NODE_FULL_HIERARCHY is not supported. NODE_CHILD and NODE_HIERARCHY require nodesId: without it, or with an empty list, the request is rejected with 400 (AE_ERR_400).
  • NODE_PARENTS has no depth limit.
  • The whole result is always returned: there is no 206.

Errors​

StatuserrorCodeWhen
400TREE_ERR_404No 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.
400AE_ERR_400method is present but has no type.
400AE_ERR_400NODE_CHILD or NODE_HIERARCHY without nodesId, or with an empty one.
400AE_ERR_400treeType is an empty list.
400AE_ERR_412treeType has a null item; the message gives its position.
400validation errormethod or treeType is missing.
400E400The body is not valid JSON.
400AE_ERR_401method.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.
401E401The X-API-Key header is missing or empty.
403AE_ERR_415The survey is not available to you.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The custom nodes that match the query: a flat array sorted by order, or a nested array when treeMode=true.