Common

In this article we will show how to create a tree with Jira tasks, assigned to the accounts, specified in a JSON file, attached to a page.

Step 1: Adding Reporting List View macro to a page

In the following step we will add and configure a Reporting List View macro. This macro is used as a container for one to many reporting data providers and appropriate number of reporting list items. The data is retrieved according to the data providers parameters and then formed to a multi-level ordered or unordered list according to the reporting list items parameters. There should be the same number of data providers and reporting list view items – one pair for each list level.

One more interesting thing to be specified here is the support of formulas in data provider queries and support for parent item references, such as CurrentParentItem and CurrentGrandParentItem. That helps in building appropriate tree views. Plus, caching is supported, thus you may have only two requests to Jira or Confluence to create a two level tree – appropriate items may be filtered out for each parent item.

Open the macro browser, locate the Reporting List View macro and place it to the page. The faster way in Confluence Cloud is to open the Insert macro menu, enter the beginning of the macro name (all Reporting macro names start with ‘Reporting’) and click on the Reporting List View macro. In this article we use Confluence Server/DC, but the same may be done in Confluence Cloud as well.

The Reporting List view macro will appear on the page. You may leave all the parameter values in default state. If you need to show some special text when no items are returned from the data provider, change the Empty response text content parameter value. If you need to show HTML instead of plain text, specify your html in the Empty response text content parameter and change the Empty response text output type parameter value to HTML. We will leave all parameters by default here.

After all parameters are set, close the macro parameters window.

Step 2: Configuring the first level of the tree – the list of users

In the following step we will prepare a page attachment file with a list of assignees, then we will add and configure the Reporting Json Data Provider and appropriate Reporting List Item macros, which, as a result, will make the top level of the tree.

Step 2.0: Preparing a Json data file with the list of assignees

Reporting Json Data Provider may read JSON data from its own property, called Json data, or from the page attachment file, specified in Json data attachment page name property. The first option is more convenient, when the JSON data block is small enough. In the case of more-less large data blocks it is advised to put JSON data into the file and attach it to the page for Reporting Json Data Provider to read it from there. In this example we will use the second option.

Open your favorite text editor and create a JSON file with the list of accounts. In our example each account has to have fullName and username fields. It’s not a mandatory format at all, you may use any JSON data. We will place the list of assignees to the assignees JSON object – just to show how to specify some specific object in an existing JSON file, when you cannot control its contents. In simplest case the list of assignees could be placed in the root of the file. Here is our example JSON file data:

{

    "assignees":

    [

        {

            "fullName": "James Smith",

            "username": "jsmith"

        },

        {

            "fullName": "Robert Williams",

            "username": "rwilliams"

        },

        {

            "fullName": "Susan Davis",

            "username": "sdavis"

        }

    ]

}

The list of issue assignees should contain existing user account info from your Jira. In our case, there are jsmith, rwilliams and sdavis accounts in our test Jira instance.

When the file is created, attach it to the current page.

Step 2.1: Adding first Reporting Json Data Provider macro to the Reporting List View macro body

Reporting Json Data Provider macro reads data from the specified JSON file and provides it to the view macro. In this step we will add a Reporting Json Data Provider macro for it to read the list of assignees from the specified JSON file for the first list level.

Click on the Reporting List View macro body to put the focus on it.

Open Insert macro menu, enter "Reporting" and click on Reporting Json Data Provider macro.

 

Specify the following parameter values:

  • Json data content type = Text only (default)
    • Json data may be processed as a static plain text or as a single expression. ‘Text only’ means the JSON data will be used as is. ‘Single expression’ means the JSON data is a formula, which should be calculated and the result should be used as an input.
  • Json data = Empty value (default)
    • Json data may be read either from the file or from the text field. The text field option is preferable when the amount of data is small. In this example we will use a more usable case – reading data from the attachment file. In this case this field should be left empty.
  • Json data attachment page name = <Current page name>
    • This parameter may be used to specify the page to read the attachment file from. The simplest way is to attach a JSON file to the current page and read data from it.
    • This parameter is supported in Server/Datacenter version only. In the Cloud version the attachment file is read from the current page only.
    • Note that the page name should not contain the ":" symbol as it is used to separate space names from the page name internally in Confluence.
  • Json data attachment file name = <JSON file name>
    • This field should be set to the name of the file with your JSON data.
  • Json data root = assignees
    • The list of assignees is specified in the assignees array, so we specify its name as a root. You may specify any path here.
  • Filter = Empty value (default)
    • We will not apply any filtering here in this example.
  • Max results = 1000 (default)
    • We are not limiting the number of results with any small number here.
    • Max number cannot be higher than 1000 anyways.

  

Save the properties of the macro, when you are done.