Common

In this article we will show how to create a tree with Jira tasks and sub-tasks.

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 issue tree

In the following step we will add and configure the Reporting Jira Data Provider and appropriate Reporting List Item macros, which, as a result, will make the top level of the issue tree.

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

Reporting Jira Data Provider as well as Reporting Confluence Data Provider macros read data from the appropriate sources and provide it to the view macro. In this step we will add a Reporting Jira Data Provider macro for it to read the list of issues from the specified Jira 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 Jira Data Provider macro.

 

Specify the following parameter values:

  • Source = Empty value (default)
    • In the case of Server/Datacenter you should specify the Application link name. If it is not specified, just like in our example, a primary link will be used.
    • In the case of Cloud the URL of your favorite Jira should be specified. Example: https://{yourSiteName}.atlassian.net/jira/
    • In the case of Cloud you should also install CelesteCS Reporting for Confluence Cloud - Jira Integration plug-in on your favorite Jira instance. As Reporting operates on behalf of the current user, it needs to be acknowledged on the appropriate Jira instance – that’s the goal of the integration plug-in.
  • Query content type = Text only (default)
    • Query may be specified as a static plain text or as a single expression. ‘Plain text’ means the specified text will be used for a query as is. ‘Single expression’ means the specified text is a formula, which should be calculated and the result will be used as a query. We will describe the second option with its unique abilities in the further steps.
  • Query = project= project = NP AND issuetype = Task ORDER BY key ASC
    • This JQL query specifies all the issues of type ‘task’ of the NP project. “NP” is a project key.
    • Any other correct JQL query may be specified here.
  • Fields = Empty value (default)
    • This value may be left by default, as the standard set of fields, returned by the Jira Data Provider will be enough for 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.

 

Step 2.2: Adding first Reporting List Item macro to the Reporting List View macro body

In the following step we will add and then configure the Reporting List Item macro, which contains all the needed information about the report list items on the first level.

Reporting List Item macro holds the parameters for a single list level. You need to add one Reporting List Item macro for each level to build a tree, so for our 2-level tree we will need to have two macros. In this step we will add the first one.

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

Open Insert macro menu, enter “Reporting” and click on Reporting List Item macro.

Initially, we will configure the Reporting List Item to show the whole item contents, copy it to the editor and then reconfigure the Report List Item macro based on this.

Set the following parameter values:

  • List item type = Unordered list item (default)
    • We are creating a tree of items and don’t need the numbers for the elements. Thus we use an unordered list.
    • You may change this to Ordered list item, if you need.
  • Body content type = Single expression (default)
    • We will specify a formula here, which will create a HTML code.
  • Body content = CurrentItem
    • We configure the Reporting List Item to show the whole CurrentItem variable contents, which is a JSON object. It will help us to find the paths to the variables, which values we need to show.
  • Body output type = Plain text (default)
    • JSON objects should be returned as a Plain text.

Publish/Save the page. You will see a single-level list with JSON objects’ content.

  

You may copy one list item content to your favorite text editor for further usage. When the JSON object is copied to another editor, open this page editor and reconfigure the Reporting List Item macro by setting the following parameter values:

  • List item type = Unordered list item (default)
    • We are creating a tree of items and don’t need the numbers for the elements. Thus we use an unordered list.
    • You may change this to Ordered list item, if you need.
  • Body content type = Single expression (default)
    • We will specify a formula here, which will create a HTML code.
  • Body content = "<img src='" & CurrentItem.fields.priority.iconUrl & "' width='16' height='16'/>" & "<span class='status-macro aui-lozenge conf-macro aui-lozenge-" & SWITCH(CurrentItem.fields.status.name, "To Do", "default", "In Progress", "current", "Done", "success", "default") & " output-inline' data-hasbody='false' data-macro-name='status'>" & CurrentItem.fields.status.name & "</span>" & "<a href='http://localhost:2990/jira/browse/" & CurrentItem.key & "'> " & CurrentItem.key & "</a> " & CurrentItem.fields.summary
    • We configure the Reporting List Item to show a priority icon, item status label, item key as a link and item summary.
  • Body output type = HTML
    • The item text should be processed as a html code.

Save/Publish the page. You should see the list with the specified project Tasks, which are the links to the appropriate issues. You may change the code to show the fields that you need.

Step 3: Configuring the second level of the issue tree

In the following step we will add and configure the second Reporting Jira Data Provider and appropriate Reporting List Item macros, which, as a result, will make the second level of the issue tree.

We will use several unique CelesteCS Reporting features, which will let us minimize Jira data reads. Here are the features of Reporting plug-in, which will help us:

  • JQL query may be specified as a formula. It is calculated before being sent to Jira. You may add any calculations, which need to be performed before the query is requested.
  • CurrentParentItem, AllParentItems parameters are supported starting from the second level of the list. You may use it in the Query calculation formula to, for example, use the parent item ID in the query.
  • CurrentGrandparentItem, AllGrandparentItems parameters are supported starting from the second level of the list. This is helpful when you are building a multi-level tree.
  • The Filter parameter of the Data Provider macro is supported. It may be used to filter out the needed values. Specifying the formula is supported here. It is convenient to read all items for a single list level and then filter it out for each parent item appropriately. For example we may read all the sub-tasks for the list at once and filter out the subtasks of the appropriate tasks.

Step 3.1: Adding second Reporting Jira Data Provider macro to the Reporting List View macro body

In this step we will add a Reporting Jira Data Provider macro for it to read the list of issues from the specified Jira 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 Jira Data Provider macro.

Specify the following parameter values:

  • Source = Empty value (default)
    • In the case of Server/Datacenter you should specify the Application link name. If it is not specified, just like in our example, a primary link will be used.
    • In the case of Cloud the URL of your favorite Jira should be specified. Example: https://{yourSiteName}.atlassian.net/jira/
  • Query content type = Text only (default)
    • Query may be specified as a static plain text or as a single expression. As we request all the sub-tasks in the project, we do not need to use formulas here.
  • Query = project= project = NP AND issuetype = Sub-Task ORDER BY key ASC
    • This JQL query specifies all the issues of type ‘sub-task’ of the NP project.
  • Fields = Empty value (default)
    • The standard set of fields, returned by the Jira Data Provider will be enough for this example, so we leave this field empty.
  • Filter = fields.parent.key = CurrentParentItem.key
    • CurrentItem is a variable for current list item on the current level.
    • CurrentParentItem is a variable for the current item’s parent item.
    • As you may see, we compare current item’s parent.key value and current parent item’s key value. If they are equal, the filter formula returns true and this item is counted as conforming the filter.
  • Max results = 1000 (default)
    • We are not limiting the number of results with any small number here.

    

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

  

Step 3.2: Adding second Reporting List Item macro to the Reporting List View macro body

In the following step we will add and then configure the second Reporting List Item macro, which contains all the needed information about the report list items on the second 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 List Item macro.

Initially, we will configure the Reporting List Item to show the whole item contents, copy it to the editor and then reconfigure the Report List Item macro based on this.

Set the following parameter values:

  • List item type = Unordered list item (default)
    • We are creating a tree of items and don’t need the numbers for the elements. Thus we use an unordered list.
    • You may change this to Ordered list item, if you need.
  • Body content type = Single expression (default)
    • We will specify a formula here, which will create a HTML code.
  • Body content = CurrentItem
    • We configure the Reporting List Item to show the whole CurrentItem variable contents, which is a JSON object. It will help us to find the paths to the variables, which values we need to show.
  • Body output type = Plain text (default)
    • JSON objects should be returned as a Plain text.

 

Publish/Save the page. You will see a single-level list with JSON objects’ content.

   

You may copy one list item content to your favorite text editor for further usage. When the JSON object is copied to another editor, open this page editor and reconfigure the Reporting List Item macro by setting the following parameter values:

  • List item type = Unordered list item (default)
    • We are creating a tree of items and don’t need the numbers for the elements. Thus we use an unordered list.
    • You may change this to Ordered list item, if you need.
  • Body content type = Single expression (default)
    • We will specify a formula here, which will create a HTML code.
  • Body content = "<img src='" & CurrentItem.fields.priority.iconUrl & "' width='16' height='16'/>" & "<span class='status-macro aui-lozenge conf-macro aui-lozenge-" & SWITCH(CurrentItem.fields.status.name, "To Do", "default", "In Progress", "current", "Done", "success", "default") & " output-inline' data-hasbody='false' data-macro-name='status'>" & CurrentItem.fields.status.name & "</span>" & "<a href='http://localhost:2990/jira/browse/" & CurrentItem.key & "'> " & CurrentItem.key & "</a> " & CurrentItem.fields.summary
    • We configure the Reporting List Item to show a priority icon, item status label, item key as a link and item summary.
  • Body output type = HTML
    • The item text should be processed as a html code.

Save/Publish the page. You should see the list with the specified project Tasks (first level) and Sub-tasks (second level), which are the links to the appropriate issues. You may change the code to show the fields that you need.

Result

As a result, we’ve got a report on Jira issues as a tree view. It shows Tasks on the top level and Sub-tasks on the second level. For each issue it shows its severity, status, key and summary. There are only two Jira query executions made to build this tree.