This article is for Data Center. Visit Cloud
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 |
---|---|
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 |
---|---|
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.
Â
Â