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
CODE

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"
          }
        }
      ]
    }
  ]
}
CODE

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

ParameterMeaning
requests[i].forestSpecForest specification that produces the forest from which the rows are taken.
requests[i].rowsArray of row IDs for which values should be loaded.
requests[i].attributesArray 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.

  1. Configure a column that shows the needed value on the Structure Board.
  2. Use your browser's Developer Tools and open Network tab.
  3. Reload structure.
  4. 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
  }
}
CODE

Parameters

ParameterMeaning
responses[i].forestSpecRequested 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].attributeThe attribute specification for which the following values are calculated.
responses[i].data[j].valuesArray 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.