Structure for Jira - Version 5.2
 

Index

Page tree

This documentation relates to an older version 5.2 of the Structure for Jira. Visit the current documentation home.

Skip to end of metadata
Go to start of metadata

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

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
  }
}

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.

 

 

  • No labels