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.

 

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 text.
  • 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.
  • Skip items with no children = Unchecked (default)
    • This parameter specifies if the items should be shown in case they don’t have child items.
    • We do not check this parameter to show the assignees, which do not have assigned items. You may change this value if you need to skip such assignees.

 

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 = "<a href='http://{yourJiraSiteName}/jira/secure/ViewProfile.jspa?name=" & CurrentItem.username & "'>" & CurrentItem.fullName & "</a>"
    • We configure the Reporting List Item to show a link to the user account name as a link to its profile.
    • Note that we specify "https" here, but you may specify use "https" as well.
    • Note that simple double quotas should be used instead of smart quotes, which are sometimes automatically inserted in text editors.
    • Set the {yourJiraSiteName} placeholder value to your Jira instance host name.
  • Body output type = HTML
    • The item text should be processed as a html code.
  • Skip items with no children = Unchecked
    • We will not skip the user accounts, which don’t have issues assigned. You may check this checkbox to skip such user accounts.

Save/Publish the page. You should see the list with the names, specified in your Json, which are the links to appropriate user profile pages. You may change the code to show the fields that you need.

Step 3: Configuring the second level of the tree – the list of issues

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

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 use the parent item field value in the query.

Step 3.1: Adding 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, assigned to the user from 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 = Single expression
    • Query may be specified as a static plain text or as a single expression. As we request the issues for a specific user account, we will use a formula here.
  • Query = "project= NP AND assignee = " & CurrentParentItem.username & " order by created DESC"
    • This JQL query specifies all the issues, assigned to the appropriate user account.
  • 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 = Empty value (default)
    • We do not use filtering here. Filtering may be used for optimization purposes. For how to use it, please, refer to other example articles for the Reporting plug-in.
  • 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/Update 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 list 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 user names (first level) and issues assigned to these users (second level), which are the links to the appropriate issues in Jira. You may change the code to show the fields that you need.

 

Result

As a result, we’ve got a report on Jira users and their assigned issues as a tree view. It shows the user names on the top level and assigned issues on the second level. For each issue it shows its severity, status, key and summary.