Value Resource

Value Resource is used to retrieve values of attributes for rows in a given forest.

To learn more about attributes, see Loading Attribute Values.

To retrieve values from Structure, you need a few things first:

A forest specification (forestSpec) for the displayed forest – same as the one used in Forest Resource. Forest specification is needed even if the values do not depend on the forest.
A list of row IDs for which the values should be loaded. Row IDs can be retrieved from Forest Resource before calling Value Resource.
A list of attribute specifications. Some examples are given below.

Loading Values

To load values use the following call

POST $baseUrl/rest/structure/2.0/value

The request should come with JSON payload that specifies which values you are interested in.

Example

{
  "requests": [
    {
      "forestSpec": {
        "structureId": 123
      },
      "rows": [
        1820,
        1842,
        2122
      ],
      "attributes": [
        {
          "id": "summary",
          "format": "text"
        },
        {
          "id": "key",
          "format": "html"
        },
        {
          "id": "progress",
          "format": "number",
          "params": {
            "basedOn": "timetracking",
            "resolvedComplete": true,
            "weightBy": "equal"
          }
        }
      ]
    }
  ]
}

As you see in this example, a request body may contain one or more request, each for a specific matrix of several rows and several attributes. A value for each pair of a row and an attribute will be calculated.

Parameters

Parameter	Meaning

Parameter	Meaning
`requests[i].forestSpec`	Forest specification that produces the forest from which the rows are taken.
`requests[i].rows`	Array of row IDs for which values should be loaded.
`requests[i].attributes`	Array of attribute specifications that should be loaded for each row.

The example shows three attributes being loaded – plain text Summary, html-formatted Key and Progress based on time tracking. For more information about available system attributes, see javadocs for AttributeSpec and CoreAttributeSpecs.

There is a simple way to learn the attribute spec that you need.

Configure a column that shows the needed value on the Structure Board.
Use your browser's Developer Tools and open Network tab.
Reload structure.
Look for a request to /value URL and see its input. Use JSON formatters for convenience.

Response

The response will contain one or more matrices with values for each pair of requested row and attribute. A list of rows is given separately. Then, for each requested attribute, a list of values is given.

{
  "responses": [
    {
      "forestSpec": {
        "structureId": 123
      },
      "rows": [
        1820,
        1842,
        2122
      ],
      "data": [
        {
          "attribute": {
            "id": "summary",
            "format": "text"
          },
          "values": [
            "Issue 1",
            "Folder 2",
            "Some Other Item 3"
          ],
          "trailMode": "INDEPENDENT",
          "trails": [ "", "", "" ]
        }
      ],
      "forestVersion": {
        "signature": -1385959428,
        "version": 1
      }
    }
  ],
  "itemTypes": {},
  "itemsVersion": {
    "signature": -558220658,
    "version": 1
  }
}

Parameters

Parameter	Meaning

Parameter	Meaning
`responses[i].forestSpec`	Requested forest spec, from which the rows are taken.
`responses[i].rows`	A list of row IDs for which the values are provided.
`responses[i].data[j].attribute`	The attribute specification for which the following values are calculated.
`responses[i].data[j].values`	Array of values. The value at `k`-th place corresponds to the row at `k`-th place in `responses[i].rows`.

If you are receiving value in any format other than html, you need to html-escape that value before adding it to the web page.

Extracting Values from a Formula Column

{
  "requests": [
    {
      "forestSpec": {
        "structureId": 1369
      },
      "rows": [
        20462
      ],
      "attributes": [
        {
          "id": "expr",
          "format": "text",
          "params": { "formula":"IF duedate :WITH Time_Left = duedate - NOW() : IF Time_Left > 0 : Time_Left ELSE : 'Overdue'","variables":{"duedate":{"id":"duedate","format":"time"}}}
          }
        ]
    }
  ]
}

The above request extracts values:

in structure 1369
for issue with rowID 20462
from the Formula column with the formula:

IF duedate :
WITH Time_Left = duedate - NOW() :
IF Time_Left > 0 : Time_Left ELSE : 'Overdue' (edited)