Skip to main content

TreeQueryRequest

Tree query: what to return (method), from which tree (treeType), from which anchor nodes (nodesId) and with which filters. Unknown properties are ignored.

method objectrequired

How to traverse the tree; see TreeQueryMethodType. Required.

typeTreeQueryMethodType (string)required

Traversal to apply from the anchor nodes. Required.

Enum ValueDescription
NODEWithout anchors, the root nodes; with anchors, the anchor nodes themselves (on the custom tree, only with includeSelected true).
NODE_CHILDThe direct children of each anchor.
NODE_PARENTSThe nodes matching text and the anchors, plus their ancestors (survey trees: up to 6 levels; custom tree: no limit).
NODE_HIERARCHYAll descendants of each anchor (survey trees: up to 6 levels).
NODE_FULL_HIERARCHYAncestors and descendants of each anchor. Not supported by the custom tree.
ALLEvery node that passes the filters. In the survey trees it takes no anchors.

Possible values: [NODE, NODE_CHILD, NODE_PARENTS, NODE_HIERARCHY, NODE_FULL_HIERARCHY, ALL]

treeTypeTreeType (string)[]required

Tree or trees to query: VARIABLES (variables and categories) and/or CARRIERS (carriers). With both values the two result lists are concatenated. The custom tree of a workspace returns data only for VARIABLES. Required.

Possible values: [VARIABLES, CARRIERS]

nodesIdstring[]

Anchor nodes. By default, node ids from a previous response; with searchField CODE, node codes; with LABEL, exact labels. In the custom tree: element ids (or ROOT_FOLDER_TARGET / ROOT_FOLDER_USER_VAR); NODE_CHILD and NODE_HIERARCHY need them there. In the survey trees, ALL does not accept anchors.

nodes object[]

Anchors as {id, uuid} pairs, where id is a node code. When present, its codes replace nodesId, so send it with searchField CODE. Not accepted with ALL in the survey trees. Ignored by the custom tree.

  • Array [
  • idstring

    code of the node (the code field of TreeNode).

    uuidstring

    id of the node (the id field of TreeNode). Only NODE_CHILD uses it, in a narrow case.

  • ]
  • typesTreeNodeType (string)[]

    Keep only nodes of these types (see TreeNodeType). Applied to every returned node, including the ancestors returned by NODE_PARENTS.

    Possible values: [FOLDER, VAR, CATEGORY, CARRIER, CUSTOM_VAR, CUSTOM_CAT, TARGET_VAR]

    subtypesstring[]

    Keep only nodes with these subtypes (the values of NodeSubtype, for example SINGLE or MULTIPLE). A value that no node has matches nothing. With NODE_PARENTS on survey trees it selects the matching nodes and their ancestors are still returned; with the other methods, nodes without a subtype (folders, categories) are dropped.

    searchFieldTreeQueryField (string)

    How the values of nodesId are matched: ID (the default) against node ids, CODE against codes and LABEL against exact labels. It does not affect text. Ignored by the custom tree.

    Enum ValueDescription
    IDAgainst the node id (the default).
    CODEAgainst the node code.
    LABELAgainst the exact node label.

    Possible values: [ID, CODE, LABEL]

    textstring

    Keep only nodes whose label contains this text. Spaces and the characters + * ^ - ( ) ! : [ ] \ / ? & ~ . are ignored: a text made only of them matches nothing.

    excludeInvalidboolean

    Custom tree only: also drop the user variables and targets whose status is INVALID. Requires validate=true.

    Default value: false
    includeSelectedboolean

    Survey trees: also return the anchors with NODE_CHILD, NODE_HIERARCHY, NODE_PARENTS and NODE_FULL_HIERARCHY. Custom tree: needed to get the anchors back with any method, NODE and ALL included.

    Default value: false
    TreeQueryRequest
    {
    "method": {
    "type": "NODE"
    },
    "treeType": [
    "VARIABLES"
    ],
    "nodesId": [
    "string"
    ],
    "nodes": [
    {
    "id": "string",
    "uuid": "string"
    }
    ],
    "types": [
    "FOLDER"
    ],
    "subtypes": [
    "string"
    ],
    "searchField": "ID",
    "text": "string",
    "excludeInvalid": false,
    "includeSelected": false
    }