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 |
---|---|
| Forest specification that produces the forest from which the rows are taken. |
| Array of row IDs for which values should be loaded. |
| 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 |
---|---|
| Requested forest spec, from which the rows are taken. |
| A list of row IDs for which the values are provided. |
| The attribute specification for which the following values are calculated. |
| Array of values. The value at |
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)