Advanced Reporting: Page Parameter

---

Making reports configurable – how to work with „Page Parameters“.

Although the report pages can always be configured over the administration page, this can be really annoying, time consuming and needs admin rights for report pages. To fix this, you can simply implement configurable parameters in the report page, which will make the report more flexible.

To show you how to do this, I will create a report page with a pie chart showing the different statuses of a selected work item type.

1. Define Page Parameter

To add such a selectable parameter, we have to go into the administration of the page and then to „Page Parameters“.

In this menu you can create a Page Parameter. They can be from different types. I will add an Enumeration (List) with all the existing work item types of the project.

So I select „Enumeration“ and there we have to select a name and id for the parameter. Under the field „Enumeration“ we have access to all enumerations of the project. I select the enumeration „workitem-type“.

Click OK, if you are done with configuring the Page Parameter. It should now be shown in the Page Parameters panel. Here you can also set directly a default value, this will enable you to test the widget configuration during administration.

If I click „Appyl“, it will set the selected value as default value.

2. Insert Page Parameters Widget

To make this Page Parameter available for users in the report page, I add the widget „Page Parameters“ to the report page.

Now I have to configure this widget. Add a title and the Page Parameter, we’ve created before:

3. Add other Widgets and configure them using the Page Parameter

Now I will add a pie chart, showing the status of a selected work item type.

To enable the diagramm to show the selected work item type, I have to change the „Query Type“ from „Lucene“ to „Lucene + Velocity“.

This change enables is, to add variables and logics into the „Query“-Area. It’s even possible to access the API via Velocity here and implement logic with this scripting language.

But in the end a valid Lucene string has to be „printed“ into the query area.

To show, how the query should look like, we can start by clicking one together via the query picker. So we have to click on the „+“ symbol below „Query“.

To see now the „true“ query, we have to convert the selected query to text. Therefore we have to click on the „down-arrow“ on the upper right and select „Convert to Text“.

Now we know, how a correct query should look like:

Now we selected all System Requirements. And if we add „Status“ to the field „Seperate By“, then the widget will show all System Requirements separated by their status.

But: We want to exchange the „systemrequirement“ with the Page Parameter variable, to make it dynamic for users.

So how do we get the variable? The variable is now available in the context of the report page. Depending on the kind of Page Parameter (String, Enumeration, Integer etc.), you have to access it differently. (Because you have to access lists in other ways than e.g. strings).

It’s described in detail in the widget SDK: in chapter 6.6 „How to use Page Parameters in Velocity and queries“ https://almdemo.polarion.com/polarion/sdk/doc/widget-sdk.pdf.

But most of the time it’s similar to this: „$pageParameters.[ID of Page Parameters].[value/values/singleValue]“.

In our case (if the id of the Page Parameter is „Work_Item_Type“):

type:$pageParameters.Work_Item_Type.singleValue.id

Tip:

You might have noticed, that on the right side in my screenshots there is printed „issue“. I did this, by using the widget „Script Block“. There you can write Velocity code, to check out what your query really returns. (I do this for the creation of the query).

It’s simply the value, that will be printed, if I enter:

$pageParameters.Work_Item_Type.singleValue.id

This way I found out, that I have to add the „.id“ at the end. Because „.singleValue“ will just return the EnumerationOption object. This object has attributes like name, id, description, icon etc. .

To find this out you have to search the Polarion API. So check out the posts:

AND

Voila – a configured report.