Building Reports

Everything covered in the section Working With Pages is applicable in LiveReport pages. However, for there are some special tools for building LiveReport pages. These are discussed in the following topics.

This section concludes with several examples for implementing report Widgets.

Overview of Reports

One of Polarion's major benefits is its ability to track actual progress of work on various artifacts of projects: requirements, test cases, test runs, change requests, etc. Data is generated as people work day to day changing the status of different Work Items, executing tests, creating plans, etc. Project stakeholders can browse various artifacts and gain a good understanding of the actual progress of the project.

However, it is possible that not all stakeholders are proficient Polarion users, or there may be stakeholders who are only interested in some specific types of information. Such stakeholders can be best served by creating reports that summarize and present just the information they need. Polarion's LiveReport Pages make it easy to build robust reports visually without scripting or programming. (Developers and other advanced users can still use custom scripting with LiveReport Pages.)

When you create a new LiveReport Page, the Widgets sidebar opens. You use the Widgets to build your report.

Introduction to Widgets

Widgets are the building blocks of reports. You insert Widgets into Pages and set their parameters to make them show the information you want in the report. You can place Widgets into any region in a Page. Widgets, combined with the layout and rich text editing features of Pages, enable you to build useful and good-looking reports that users can print or export to PDF.

There are 3 main categories of Widgets:

  • Chart Widgets retrieve and display project data as some type of chart.

  • Utility widgets provide data tables, object counts and interactivity for report users.

  • Scripting widgets provide programmers the means to implement custom functionality in reports, should this be needed.

The Widgets sidebar is organized into several categories containing groups of related Widgets - scripting, for example. (The Categories can be customized by a developer.)

TIP

You can see a brief description of each of the available Widgets in the Widgets sidebar by hovering your pointer over each one.

Using Widgets

This section describes the basic things you need to know when using Widgets in a Page: inserting, copying, editing, and deleting. It is recommended that you first read the topic Editing Pages.

Inserting a Widget

You can insert Widgets in any region of a Page. When developing a new report, it is usually best practice to construct the Page layout first (see Modifying Page Layout).

To insert a Widget:

  1. Open the Widgets sidebar, if it is not already open. (Use the Show Sidebar icon on the Page toolbar.

  2. Place the insertion cursor inside a region at the point where you want to insert the Widget.

  3. In the sidebar, click on the Widget you want placed in the Page. The Widget is rendered visually in the Page and selected for editing. The Parameters sidebar opens, replacing the Widgets sidebar and displaying the parameters of the Widget you just added.

After placing a Widget into a Page, you can immediately proceed to configure its parameters (see Making Widgets Work, or you can place other Widgets to complete the layout of your report, and come back and configure Widget parameters later (see Editing Existing Widgets). If you decide to complete the layout first, close the Parameters sidebar and reopen the Widgets sidebar from the Show Sidebar button on the Page toolbar.

Editing Existing Widgets

You opt to edit Widget parameters after completing the report layout, or you may find at some point that you need to modify the parameters of an existing Widget.

To edit and existing Widget:

  1. Open the Page for editing in the Page Designer.

  2. Locate the Widget in the Page Designer and click on its yellow header to open the Parameters sidebar and the parameters for the selected Widget.

Widget Layout and Sizing

You can explicitly set the height and width of chart Widgets to achieve a desired page layout. The Advanced section of the Widget parameters contains fields Height and Width, which you can set to achieve the desired layout of a chart on a Page. Chart Widgets are block type Widgets (as opposed to in-line type), and the chart rendered inside them is always centered within the block.

  • Height must be specified only in pixels.

  • Width can be specified in pixels, or as a percentage. Examples: 350 or 75%.

  • For the Plan Progress Widget, you can specify only the Width parameter.

Note

These parameters are also accessible to developers via the Polarion API.

Inserting Content Before or After

After a Widget is placed into a Page region, you may want to insert another widget, or insert other content before or after that Widget. You need to use the special menu commands found on the header of each widget.

To insert content before or after an existing Widget:

  1. With the page open for editing in the Page Designer, click on the (Actions) icon on the Widget's header.

  2. In the drop-down menu, select Insert Paragraph Above or Insert Paragraph Below.

  3. Insert another Widget or other content in the added paragraph space.

    Note

    Users of Polarion PRO license can insert paragraphs above or below Widgets, but cannot insert new Widgets.

Copying Widgets

You can optionally copy a Widget and paste it to a different region or Page. This can save time if you need several Widgets of the same type, but with minor differences in the parameters. You can just tweak the parameters in the pasted Widget.

You can optionally copy the source code of a Widget you have inserted and configured visually. This can be useful for developers who are writing extended or custom Widgets or developing custom scripts for use in one of the scripting Widgets.

To copy and paste a Widget:

  1. With the Page open for editing in the Page Designer, click the (Actions) icon in the header of the Widget you want to copy.

  2. On the drop-down menu, choose Copy Widget.

    If your browser has security restrictions that block it from direct programmatic access to your clipboard, a dialog appears prompting you to use the Copy keyboard shortcut. If you see this dialog, you can always just select the Widget in the Page and press your Copy shortcut.

  3. Locate the insertion cursor in the region where you want to paste the copied Widget, at the point where you want it inserted. Then press your Paste keyboard shortcut (Ctrl+V, Command+V, etc.).

To copy a Widget's source code:

  1. With the Page open for editing in the Page Designer, click the (Actions) icon in the header of the Widget you want to copy.

  2. On the drop-down menu, choose Copy Widget Source Code.

    If your browser has security restrictions that block it from direct programmatic access to your clipboard, a dialog containing the source code appears, which prompts you to press your Copy shortcut to copy the code from the dialog. Otherwise, the source code is silently copied to your clipboard.

Deleting Widgets

To delete a Widget:

  1. With the Page open for editing in the Page Designer, click on the header of the Widget you want to delete.

  2. Press the Delete key on your keyboard.

TIP

You can also use the Delete command on the Actions menu of the Widget's header.

Making Widgets Work

When you place a Widget into a page, you see some graphical rendering of it, but no data. In order to make the Widget perform its intended function, you must edit its parameters in the Parameters sidebar. Each Widget has its own set of Parameters that work together to retrieve and render information. There are several commonly used ones which are best illustrated in an example of a simple table of project Work Items. Many of the parameters are applicable for charts as well.

Add a Widget

All widgets can be used on LiveReports, Info Pages and Plans.

To add a Widget

  1. Select a LiveReport / Info Page or a Plan and launch the Widgets sidebar.

    • For a LiveReport or Info Page:

      1. Choose a LiveReport or Info page from a Space under the Documents & Pages topic.

      2. Click Expand Tools at the top of the page.

      3. Click Edit.

    • For a Plan:

      1. Choose a Plan: from the Plans topic.

      2. Click then Customize Plan Report.

  2. Click in the page box where you want to insert the widget.

Kanban Board

The Kanban Board widget lets you create a drag and drop Kanban style board for Work Items. The number of columns (workflow states), the type of Work Items to include, and the board's appearance are all defined in the Kanban Board: Parameters sidebar.

Figure 16.5. Kanban Board

Kanban Board
Add a Kanban Board
  1. Select a LiveReport / Info Page or a Plan and launch the Widget's sidebar.

  2. Click in the page box where you want to insert the board.

  3. Select the Work Items or Planning tab under the Widgets sidebar.

  4. Click on the Kanban Board icon.

  5. The Kanban Board: Parameters sidebar opens on the right.

  6. In the Scope field, Select a Project, Project Group or the whole Repository.

  7. Select a Query Type. (If you are unsure what kind of query type to use, just leave it on Lucene. You will be able to build a query graphically in the steps that follow.)

  8. Select a Work Item Type.

    • To add a single Work Item type to the board, you can select it from the Type drop-down list.

    • To select more than one Work Item type, leave the default Work Item selected.

  9. The Query field is where you'll define what Work Items are added to your Kanban board.

    1. If you're familiar with Polarion's Advanced command-line query syntax, you can paste your query directly into the field.

    2. Click to define what items to include graphically.

    3. Click a set of options to include and click . ( can be clicked multiple times to add additional criteria.)

      In large projects, you can combine the command-line and graphical query options to really fine-tune your selection.

  10. Add a Title for the first status, for example Open, in the Columns section.

  11. Click , choose a status item from the Available Items on the left and click . (You can add more than one.)

  12. Click OK.

  13. (Optional) Click under Sort By and select how the Work Items are sorted and the direction that they should be sorted in.

  14. Click OK.

  15. Click Add Column and repeat steps 10 - 14 for each workflow status.

  16. (Optional) Add the fields that you want to appear under the Work Item Properties Sidebar Fields. (Launched when a card is clicked on.)

    • AS A REPORT EDITOR: (Edit mode):

      1. Click under Work Item Properties Sidebar Fields to add any fields that you want to appear under the Work Items Properties sidebar.

        (Launched when a Kanban, Table or Work Items Board widget item is clicked.)

      2. Select a field on the left, click and click OK when you've finished adding the fields you want to include.

      3. The selected fields will appear in the Work Items Properties sidebar when a card is clicked on.

    • AS A USER: (Anyone who clicks on an item in a widget that supports the Work Item Properties Sidebar)

      (The fields will be added to the Work Item Properties Sidebar of all the Kanban, Table and Work Items Board widgets in the selected project.)

      1. Click on a Card, Swimlane or table item.

        The Work Item Properties Sidebar appears on the right.

      2. Click the icon on the top right and click Select Fields.

        The Select Fields dialog appears.

      3. Select a field on the left, click and click Set as Personal when you've finished adding the fields you want to include.

        Work Item Properties Sidebar Fields

        - Greyed out fields can only be removed when the report is in Edit mode.

        - The fields will appear in the Work Item Properties Sidebar for all Kanban, Table and Work Items Board widgets.

        - Fields added by a user (when not in Edit mode), will only be visible to them.

        - Add fields in Edit mode above if you'd like other users to also view them by default.

        - The added fields will only appear for the selected Work Item type ( etc.) and Project.

  17. Click Apply or follow the instructions in the following Customize the Kanban Board's Appearance section to change the board's appearance.

Customize the Kanban Board's Appearance

You can customize the appearance of the cards by adding custom velocity snippets. You can change the color of the card, remove the status border color, show different Work Item fields, re-arrange the fields already rendered and more. The custom Velocity scripts will be rendederd instead of the default java scripts. Default velocity snippets are included with the widget under the Board Script and Card Script parameters and are a great starting point. The sample scripts mimic the java rendered output that's provided out of the box.

Customization Options
  • Board Script - Is inserted at the beginning of the board and should always be used to add custom css styles and/or java script common for all your cards.

    (This avoids having to duplicate them for each card.)

  • Card Script - Defines the content that appears within the cards.

    The Card Script Velocity script allows for the following additional objects:

    $workItem - The Work Item rendered in the card.

    $columnIndex - The column that the card is rendered on.

A customization example:

  1. Open the Kanban Board: Parameters sidebar if it's not already opened.

    (Click on the top right of the board in Edit mode.)

  2. Click Advanced.

  3. Define The maximum # of results per columns that appear.

    (Click the Showing #/# link on the bottom of a column to see the next list of items.)

  4. Click Yes to Enable Customization.

  5. Click on Board Script. (For a fullscreen view of the script hit F11. Hit Esc to exit fullscreen view.).

  6. Change the background color of the card by adding "background-color: #d0d2e0;" to ".kanbanWorkItemDiv".

    (#d0d2e0 can be replaced with any color you'd like.)

  7. Change the gradient of a long title by changing the "background" property in ".kanbanWorkItemTitleGradientDiv" to,

    "background: linear-gradient(to bottom, rgba(255, 255, 255, 0), #ccffff) repeat scroll 0 0 rgba(0, 0, 0, 0);"

  8. Enable the Work Item Properties Sidebar by adding:

    .polarion-sidebar-highlight .kanbanWorkItemDiv {
          background-color: #fff9e8;
          }
                     
  9. The entire Board Script would look like the following:

    kanbanWorkItemDiv {
      padding: 7px 3px 3px 7px;
      box-sizing: border-box;
      border-left: 5px solid;
      border-right: 1px solid #EEEEEE;
      border-top: 1px solid #EEEEEE;
      border-bottom: 1px solid #EEEEEE;
      border-radius: 5px;
      position: relative;
      background-color: #d0d2e0;
    }
    ... 
    .kanbanWorkItemTitleGradientDiv {
      bottom: 0px;
      height: 12px;
      left: 0;
      position: absolute;
      width: 100%;
      display: inline-block;
      background: linear-gradient(to bottom, rgba(255, 255, 255, 0), #d0d2e0) repeat scroll 0 0 rgba(0, 0, 0, 0);
      filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#00FFFFFF', endColorstr='#FFFFFFFF', GradientType=0);
     }
    ...
    
    .polarion-sidebar-highlight .kanbanWorkItemDiv {
        background-color: #fff9e8;
    }
    
    ...
     
  10. Click Apply.

    The example script above changes the Kanban board's appearance to:

Revert Changes

The Work Item Properties sidebar and the ability to drag and drop are still available when customizations are enabled and you can always revert to the internal Java rendring by setting Enable Customization to No.

Table of Work Items Example

A simple but useful report element might be a table of unresolved Work Items sorted by type, severity, and current status, and showing several key field such as ID, Title, Status and Severity.

If you have the appropriate permissions, you can modify a Work Item's fields by clicking on it.

Figure 16.6. Table of Work Items Widget

Table of Work Items Widget

The fields that appear can be configured in the Table - Block: Parameters sidebar.

To launch the Table - Block: Parameters sidebar.

  • For a Plan: Click on Customize Plan Report above the table widget.

  • For LiveReport and Info Pages: Click on Edit above the table widget.

Then follow the instructions defined in Parameters Sidebar section below.

Figure 16.7. Table-Block Widget Parameters

Table-Block Widget Parameters

Note

The Work Item Properties Sidebar Fields only work for Work Items.

See the Add a Kanban Board section to learn how to define what fields appear and what widgets are affected.

The table will show a subset of all available project data, so it's necessary to set some parameters to retrieve the desired data.

  • Scope: Scope of the data to be retrieved. The default is the current project, but you could retrieve data from a different project from the one in which you are currently working, or from the entire repository. In this example, the scope is the current project.

  • Query Type: The full arsenal of Polarion's data retrieval capabilities are available here, including Apache Lucene query language, SQL, or combinations of Lucene and Velocity, or SQL and Velocity. For the purposes of an easy example, Lucene is used, as many users are familiar with this type of query, and the Visual Query Builder is integrated in Widgets enabling users who don't know a query language to build queries visually.

  • Type: Specifies what main artifact type is the basis for the data. You can opt for the data to be Work Items, Documents, Plans, Test Runs, or Pages. You can refine this by selecting one of the sub-types defined for the different artifact types (if any).

    For example, if the artifact type is Work Item or Document, you can select the type in the list. For example, for the Work Item artifact type, there might be Requirements, Test Cases, Issues, Tasks, etc. The Document artifact type might have sub-types such as Requirements Specification or Risk Analysis. The sub-types list varies according to the Scope. For example, Repository scope will list all Work Item and Document types defined in the global configuration, whereas selecting a project limits the list to the types defined for the selected project.

    For this example, Work Item is selected, because the table must show Work Items.

  • Query: Use a query to further refine the data shown in the table. In this simple example, Lucene is selected as the query type. For Lucene queries, the same Visual Query Builder tool you may already have used in the Work Item Tracker is available. You can use it to add multiple visual query elements to the Query to build queries ranging from ultra simple to very complex. For this simple example, only one element is added: a query on the Resolution field, for a value of "unresolved".

  • Columns: Columns in the table will display Work Item fields, because Work Item is selected in the Type parameter. You can specify the columns to show in the table, and their order, using the Select button under the Columns field. (The selection dialog is the same one you may have used to customize the Work Items table in the Work Item Tracker.)

    For this example, the ID, Title, Type, Status and Severity fields are selected to appear as table columns.

    TIP

    What you can select to show in Columns depends on the artifact type selected in Type. Work Items will have different items than Documents or Test Runs.

  • Sort By: This will specify how the Work Items are sorted in the table. The specification of the example called for sorting by type, severity, and current status. Sorting by Type first will cause the different Work Item types to be grouped. So all Issues will appear first, followed by all Change Requests, Requirements, and finally Test Cases. Within those groups, the rows are sorted by severity in ascending order. Finally, the rows for a given severity are sorted by the current status of the individual Work Items.

    This field also has a Select button, which leads to the same dialog in which you can select the fields to sort on, the sort order (ascending/descending), and the order of the fields.

  • Work Item Properties Sidebar Fields: Select the fields that will appear in the Work Item Properties Sidebar.

  • Show Top Rows: You may need to expand the Advanced section of the sidebar to see this field. This can be an important parameter if the table is potentially very large. The default is 50, meaning the table will only show the first 50 items matching the query, and will display a link that will open the Work Item Tracker in a new browser tab and load all the marching Work Items.

Important

Click the Apply button in the sidebar to update the visual rendering of the Widget in the Page Designer after modifying parameters. This applies to all Widgets.

Users do not see any changes to the Page until you save changes you make in the Page Designer. After the Page is saved, the report is "live" in the sense that the table reflects the status of the items in the project as of the time the user loads the report page. Users can see any later changes in the data by refreshing the page in their browser.

Work Items Board

This widget creates a drag and drop Work Item Board on LiveReports, Info Pages and Plans.

Transitions and Statuses are based on the configured Work Item's workflow.

If there are no additional workflow conditions or required fields, a Work Item is automatically saved when dragged to a new state.

If a Work Item requires additional input, for example a Resolution, the Work Item Properties sidebar automatically appears when the item is dragged to a new state.

Figure 16.8. Work Items Board

Work Items Board

The properties of a Swimlane (parent Work Items) and their children (Cards) can be viewed and modified by clicking on their whitespace.

Enter the required information and click Work Items Board Save.

See Define what appears Work Item Properties sidebar to customize its visible fields.

Note

The Work Item Properties Sidebar Fields only work for Work Items.

See the Add a Kanban Board section to learn how to define what fields appear and what widgets are affected.

Figure 16.9. Work Item Properties Sidebar

Work Item Properties Sidebar

Enter the required information and click Work Item Properties Sidebar Save.

Note

The Work Item Properties sidebar is read-only in History and Baseline views.

Define what Fields Appear in the Parameters Sidebar

Figure 16.10. Work Items Board: Parameters Sidebar

Work Items Board: Parameters Sidebar

  1. Open the Parameters Sidebar.

    • For a Plan: Click on Customize Plan Report above the table widget.

    • For LiveReport and Info Pages: Click on Edit above the table widget.

  2. Click Select.. below Work Item Properties Sidebar Fields for cards.

  3. The Select Items dialog appears.

  4. Select an item from the Available Items box on the left and click .

    (The item appears in the Selected Items box on the right.)

  5. Click Apply.

  6. Repeat this process for all the fields you would like to add to the Work Item Properties Sidebar Fields for Cards and click OK.

  7. Follow the same steps to add fields for Swimlanes by clicking Select.. below Work Item Properties Sidebar Fields for Swimlanes.

Scripted Chart

A scripted chart renders a chart defined by a custom Velocity or JavaScript.

To add a Scripted Chart.

  1. Select a LiveReport / Info Page or a Plan and launch the Widget's sidebar.

  2. Click in the paragraph that you want to add the widget to.

    (You can add a new paragraph box before or after the existing boxes or resize them.)

  3. Click on the Charts tab in the Widgets sidebar.

  4. Click on the Scripted Chart icon.

  5. Add a Velocity or JavaScript into the Script field.

    (If you don't have a script of your own, you can paste the example below in and customize it.)

    {
            chart: {
                type: 'areaspline'
            },
            title: {
                text: 'Average Weekly Fruit Consumption'
            },      
            xAxis: {
                categories: [
                    'Monday',
                    'Tuesday',
                    'Wednesday',
                    'Thursday',
                    'Friday',
                    'Saturday',
                    'Sunday'
                ]
            },
            yAxis: {
                title: {
                    text: 'Kilograms of Fruit'
                }
            },
            series: [{
                name: 'John',
                data: [3, 4, 3, 5, 4, 10, 12]
            }, {
                name: 'Jane',
                data: [1, 3, 4, 3, 3, 5, 4]
            }]
        }
                    

    (Click F11 to adjust the script in full-screen mode and ESC to exit full-screen mode.)

  6. Click Apply. The chart will be rendered and appear on the page.

  7. Click .

Simple Chart Example

A simple but useful report might be one that shows a chart of unresolved Work Items with high severity values currently in the repository, separated by Work Item type, reporting also the total number of Blocker and Critical defects. Such a report requires only 2 Widgets:

  • Separated by - Pie chart

  • Object Count - inline

After placing the pie chart Widget in some region of the Page, set its parameters as follows:

  • Title: Enter a title that describes what the chart shows. For this example, something like "Unresolved Blocker & Critical Work Items by Type".

  • Scope: In the case, the chart is reporting across the entire repository, so Repository is selected in this parameter.

  • Query Type: Again, this example uses Lucene because it provides the possibility to build queries visually. (Report authors who know Velocity or SQL can opt for to use these types of queries.)

  • Type: The artifact type for this report is Work Items, so Work Item is selected for this parameter.

  • Query: for this chart, two query elements are needed. The report is for unresolved Work Items, so the first query element is for that. Simply choose Unresolved in the Favorites section of the Query Builder. Then add another query element to select the severity level of the unresolved items. Select Severity in the Query Builder panel. The report is to show items with Blocker or Critical severity, so select both of these in the value picker before closing it.

  • Separate By: Recall that the report is supposed to show Blocker and Critical items by Work Item Type. The chart Widget makes this quite easy. Simple select Type in this field to separate the matched items by type.

  • Show Data Labels: This parameter controls whether or not the pie chart's wedges will be labeled. The Yes option is a good choice in this example.

  • Show Zero Values: This parameter controls whether or not the chart should include a segment for zero matched items. For example, are no Change Requests with Blocker or Critical severity, selecting Yes will cause the chart to render a small wedge reflecting this.

Remember to click the Apply button to reflect changes in the chart rendering on the Page. To complete this report as specified, add a paragraph above or below the chart Widget, and add an Object count - inline Widget the insertion point. Set this Widget's parameters as follows:

  • Scope: Select Repository, since the requirement is to report a count of items in the repository.

  • Query Type: Again in this Widget, select Lucene to keep things simple.

  • Type: The Widget is counting Work Items, but this needs to be refined to just the Defect type. If the repository contains this type, it will appear in the types list under Work Items. This example assumes there is a type "Defect" and selects that type in this Parameter. Now the Widget will render a count of only Defect type items.

  • Query: Because Lucene is the query type, the Visual Query Builder is available. Again, two visual elements are needed: one to select only unresolved items, and one to select the severity levels to be included in the count. In this case, Blocker and Critical are selected.

    If you click Apply now, a number will appear in the paragraph of the Page where you inserted the Widget. However, another user reading the Page will not know what the number means.

  • Text Before and Text After: These fields provide a quick way to include some explanatory text before and after the object count.

    In this example, the report author might enter There are currently in the Text Before parameter, and BLOCKER & CRITICAL Defects in the repository. in the Text After parameter. On clicking Apply, the Widget renders There are currently 42 BLOCKER & CRITICAL Defects in the repository., assuming there are 42 items that match the query in the parameters.

Trend Chart Example

Charts showing trends can be highly useful. For example, suppose you are interested in comparing the trend of high-severity vs. low-severity Issue type Work Items. This is easily done with the Multi-line Trend Chart. You can configure the chart with one data set to show high-severity items and one to show low-severity items. If you want to see more tends in the chart, you can add more data sets.

  1. Place a Multi Line Trend Chart Widget in some region of the Page.

  2. In the default Set, specify the scope of the Work Items (a project or the entire Repository), select Lucene as the query type. Then in the Query section of the Set, build a query with 2 elements: Type: Issue, and Severity: Basic, Low (or whatever the lowest severity values are for the Work Item type Issue in the selected Scope).

    Set other fields... Set Name: Low Severity, Color: Gray.

  3. Now click Add Set and configure the second Set to query for high-severity Issue type items, naming the Set High Severity, and using a different color, such as Red. Note that in Widgets that have the Color parameter, you can specify common color names supported in HTML (Red, Blue, Cyan, Black, etc.) or hexadecimal values (#ed1c24, #0000ff, etc.) For example, multi data set type chart Widgets use the Color parameter to visually differentiate the data.

  4. Enter a date range in the Dates parameter. This parameter is available in chart Widgets where the data retrieved need to be filtered by a date range. The From and To fields enable you to configure the time scope of the trends you want the chart to reflect. The Horizontal Scale Axis enables you to set the frequency of points plotted, and when plot points are calculated. For example if the scale is Month, you might specify a plot point value of 1, meaning data from the first day of each month is used for the plot point.

  5. Click Apply to reflect the configuration in the chart on the Page.

If you want to configure additions Sets, use Add Set, and configure each one as desired, building a query in each Set to retrieve the data you want, which will appear as another line in the chart.

TIP

The Multi Data Set Pie Chart also provides the possibility to reflect multiple sets of data in a pie chart format.

Simple Plan Example

You can use the Widgets in the Plans group to report information about Plans such as activity and progress, and provide some interactivity such as creating a new child Plan, setting Plan status, and opening a Plan. The Widgets for this example are:

  • Plan Label

  • Plan Status Button

  • Open Plan in Table

  • Plan Activity Stream

  • Plan Progress

Figure 16.11. Easy Plan Info Page

Easy Plan Info Page

Useful Plan info and interactivity using 5 easily configured Widgets

Plan Label

Create a new region and insert an appropriate heading ("Release Plan", for example). Below the heading insert a Plan Label Widget. This Widget shows the name of a Plan, which is a hyperlink that opens the Plan. It displays any existing child Plans, with the same hyperlinking to open them, and provides the option of creating a new child Plan, based on some template Plan, directly from the Page. Set the Widget parameters as follows:

  1. Plan: use the Select button to select the Plan you want for which you want to report information. For purposes of this example, select a Release plan.

  2. Assume you want to allow users to create a new child Plan directly from the Page. In the Child Template field, use the Select button and choose a template to be the basis for child Plans of the one specified in the Plan field. For purposes of this example, select Iteration, as an iteration Plan would typically be a child of a release Plan.

  3. In Show Add Button click Yes. This will allow users who have permission to create new Plans to do so from the finished Page.

  4. Click the Apply button to complete the configuration of this Widget.

Open Plan in Table and Plan Status

Beneath the Plan Label widget, insert these Widgets, leaving a few horizontal spaces between them:

  • Open Plan in Table

  • Plan Status Button

In the parameters for both these Widgets, select the same plan you selected in the Plan Label widget.

With these Widgets in place and configured, a Page user will be able to open the Work Items of the specified Plan in the Work Items table, and change the status of the specified Plan directly from the Page.

Plan Activity Stream

On your Page, you can easily show the Activity Stream of any Plan, enabling users to see the latest activities. To do this:

  1. Create a new region below the one you created earlier, and enter some heading like "Plan Activity".

  2. Place a Plan Activity Stream Widget into the region and use the Select button in the Parameters sidebar to select a Plan. For the purposes of this example, select the same Plan you selected in the Plan Label widget parameters.

  3. Expand the Advanced field and enter a number in Max. number activities to show. For example, if you enter 5, the stream in the finished page will show only the 5 most recent activities on the selected Plan. The Widget running in the finished Page will enable users to see more activities.

  4. Click the Apply button to finish the configuration of this Widget.

Plan Progress

The Plan Progress Widget renders a graph and statistics of a selected Plan that show the current progress of the Plan. The information is updated when a user loads the finished Page. Refreshing the Page refreshes the information.

  1. On the region menu of the region you added above, choose Split Region, or create a new region wherever you want on the Page, and add a heading like "Plan Progress".

  2. Insert a Plan Progress widget in the new region beneath the heading.

  3. In the Plan use the Select Plan button to select the same Plan you selected earlier in the Plan Label Widget.

  4. Review the two options Show Ideal Progress and Show "To Do". This information is shown by default. If you want to exclude one or both, click No in the option field.

  5. Optionally set the chart width. Expand Advanced and enter a value in pixels or percentage. For example: 600px or 85%.

  6. Remember to click the Apply button to finish the Widget configuration.

The example Plan information is now complete. Save the report Page and click Back. The Page is now ready for users.

Simple Test Run Example

A test manager may not want to grant testers full access to Test Runs, where they could access templates, properties, and other features, but still wants to enable them to view information about a Test Run and even execute it. Using special Widgets in the Test Runs category of the Widgets sidebar, the manager can quickly construct a Page that...

  • Displays the name of the Test Run.

  • Displays the current status of the Test Run and its Test Cases.

  • Enables a tester to execute the Test Run in Polarion.

  • Enables a tester to export Test Cases to Excel, and after executing them externally, import the results back to the Test Run.

  • Change the workflow status of the Test Run.

  • View electronic signatures and test records.

Figure 16.12. Test Run Page Example

Test Run Page Example

Simple Test Run Page and Widgets

Getting Started

To start building the Page:

  1. Create a new LiveReport type Page and give it an appropriate name. This name appears formatted as Title in the new Page. Do not make the page name the same as the Test Run name because a Widget will display that. Consider if you might want to reuse the Page for different Test Runs over time and if so, make the page name more or less generic.

  2. Under the title text, place a Test Run Label Widget. In the Widget's parameters, click the Select button, and in the dialog select the Test Run for which you are building the Page. You can optionally choose whether to have the Widget display the name of the Test Run Template from which the Test Run is derived, in addition to the Test Run's name. Always click Apply when finished with parameters.

Enabling Display of Test Run Status

It is generally useful for the page to show the current status of the Test Run and the Test Cases selected for it. To do this:

  1. Insert a new region below the first one and split it.

  2. In the left region, type a heading like "Status Overview" and format it as e.g. Heading 2. Then, under the heading, insert a Test Run Overview Widget, and in its parameters, select the same Test Run as you selected in step 2 above, and click Apply.

    Note

    You will select the same Test Run for all Widgets in this Page, since this example deals with only one Test Run.

Enabling Test Run Execution

You can set up the Page to enable testers to execute the Test Run (they must have the necessary permission for this). The example page will enable both internal execution in Polarion and external execution of the Test Run via Excel round-trip. On a real page, you would most likely provide only one of these options.

  1. In the new empty region on the right, type a heading "Execute Test Run" and format it as before. Under the heading, insert an Execute Test Run Button Widget, select the Test Run in its parameters. You can optionally specify sorting of the Test Cases. Click Apply when finished.

    TIP

    Center-align the Widget in the region.

  2. Under the button Widget, insert two additional Widgets: Export Tests and Import Manual Test Results. In the parameters of each one, select the Test Run.

    In the export Widget, you can optionally select a subset of the Test Run's Test Cases by means of a query. For example, it make sense to only export Test Cases with the Open status (status:open). This and the remaining parameters are optional:

    • Specify the name of the Excel export template that should be used by the exporter only if you have some custom export templates and do not want the default template to be used.

    • A default filename for the exported Excel file is used if you do not specify a filename.

    • Optionally change the label displayed to users. For example, if you have a query to select only open Test Cases, you can change the label to, e.g. Export Open Test Cases to Excel.

  3. Under the export Widget, place an Import Manual Test Results Widget. Select the Test Run as with the other Widgets, and optionally change the Widget label. Click Apply when finished.

  4. Add a new region to the bottom of the Page and split it in preparation for the next steps.This is a good time to save your work in progress.

Enabling Test Run Status Change

In the new left-hand region, create a heading like "Set Test Run Status", and under it insert a Test Run Status Button Widget and select the Test Run in its parameters.

Displaying Electronic Signatures

You should only implement this if your project is configured to use electronic signatures for Test Runs. Otherwise you can skip it.

  1. In the empty right-hand region, create a heading like "Electronic Signatures", and under it insert a Test Run Signatures Widget and select the Test Run in its parameters. Click Apply when finished.

  2. Add a new region to the bottom of the Page in preparation for the next steps. (Do not split it.)

Displaying Test Records

In the new region, insert a Test Records Widget and select the Test Run in its parameters. In the Columns parameter, select which test record information you want to display in the Page. Click Apply when finished.

The Page is now complete. Save it, click Back button, and it is ready for use. Once you understand the Widgets, you can probably build a functional Page like this one in fifteen minutes of less.

There are some other Test Run related Widgets not used in this example:

  • Test Run Activity renders the selected Test Run's activity stream in the page.

  • Import Automated Test Results enables the Page user to select a file with xUnit test results and import it to the specified Test Run.

Making Reports Interactive

You can provide a limited level of interactivity in reports using Page Parameters. This is considered an advanced feature. It enables you to provide report viewers with some options for selecting the data they want to see. For example, you might enable users to select a date range for a trend chart, or the number of rows they want to see in a table.

Page parameters can only be used with many of the Widgets, and some of their parameters. You can tell if a parameter can be associated with a page parameter by clicking the small gear icon displayed in it's section of the Parameters sidebar, and then clicking Parameters to show the Page Parameter(s) compatible with that Widget Parameter, if any have been defined.

You can only have one Page Parameters Widget in a Page. You need to decide what parameter values you want report viewers to be able to change in which widgets, define Page Parameters for them, and specify all of them in the single allowed Page Parameters Widget.

For example, suppose a Page contains a multi-line trend chart, one or two pie charts, and two tables. You might decide to allow report viewers to interactively specify:

  • A date range in the trend chart

  • The number of rows to show in the tables

  • Whether to show data labels in the pie charts.

At runtime, the Page Parameter includes an action Save as Default. A user can change the values and click this link to have the changed values become the defaults. Other users accessing the page will see the values in the Page Parameter widget.

Defining Page Parameters

Assuming the Page is otherwise complete, with the Widget parameters all configured, the first step in providing user interactivity is to define the Page Parameters. With the Page open for editing in the Page Designer, open the Page Parameters sidebar (from the Show Sidebar icon on the Page Designer toolbar).

Three Page Parameters are needed for the example stated earlier in this topic. You create new Page Parameters using the Parameter button, which drops down a menu of data types:

  • String

  • Integer

  • Boolean

  • Enumeration

  • Date

Each Page Parameter must correspond to the data type it will manipulate in the Widget(s). For example, to allow users to set a start date in a trend chart, the Page Parameter must be of the Date type. To allow users to specify the number of rows to show in a table Widget, the Page Parameter must be of integer type.

When creating a Page Parameter of type String, Integer, Boolean or Date you must specify two properties: Name and ID. Name is what report users will see in the page. ID is the identifier used by the system. By default, the values are identical. The difference is that ID supports only ASCII characters. If you need the label to display a different character set, specify ID using only ASCII characters, and Label using your language's character set.

A Page Parameter of type Enumeration has several additional properties:

  • Scope: default is the current project. You can optionally select Repository, or another project. The selection here determines the types available in the Work Item Types list and the enumerations available in the Enumeration field's pick-list.

  • Work Item Types: The types configured in the selected Scope appear in the list. The selection here affects the list of enumerations in the Enumeration field. Depending on the selection it may refine the list and filter out some of the items present as a result of the selection in Scope.

  • Enumeration: The enumerations (default and custom) for the selected Work Item type in the selected scope appear in the list.

  • Allow Multiple Values: enables selection of multiple values by the page developer, and later by the page user.

  • Allow No Values: provides the Page user possibility of not selecting any value for the Page Parameter. The -- not selected -- option appears to users in the drop-down list of enumeration values.

For example, you might want a Page Parameter to enable Page users to specify the specific types of Work Items planned in some Plan for some release... Requirements without Test Cases, for example.

The parameters needed for the example for this topic are:

  • Parameter labeled "Dating From" of type Date

  • Parameter labeled "Show Pie Chart Labels" of type Boolean (i.e., true/false, yes/no)

  • Parameter labeled "Table Rows" of type Integer

Connecting Page and Widget Parameters

After defining the Page Parameters, they must be "connected" to the parameters of the Widgets they manipulate. For example, the Page Parameter "Dating From" needs to be connected to the Dates - From parameter of the multi-line trend chart widget:

Figure 16.13. Connecting Page Parameter to a Widget Parameter

Connecting Page Parameter to a Widget Parameter

Connect an existing Page Parameter to a Widget Parameter of the same type

You can tell if the Widget can be manipulated via an existing Page Parameter by clicking the gear icon in a Widget parameter, and clicking again on Parameters. This will display the Page Parameters that are compatible with this Widget parameter. Check the Page Parameter you want to use. In this example, you can check "Dating From" to connect that Page Parameter to this Widget parameter. The end result for your report users will be that they can select the start date in the date range rendered by the chart.

Figure 16.14. Connecting Page Parameter to a Widget Parameter

Connecting Page Parameter to a Widget Parameter

Users can choose the start date for charts connected to the Page Parameter

TIP

Several chart Widgets have Date type parameters. These can be either absolute or relative dates. Relative means the retrieved data is relative to some point in time, such as "Today", "2 weeks ago", "6 months ago", etc. rather than for some concrete data such as "January 22, 2014".

The report author can specify either or both for a Date type Widget parameter. A Page Parameter linked to such a Widget parameter will render the user's input options accordingly.

The process is the same for the other Page Parameters.

  • The Advanced > Show Top Rows parameter of the Table Block Widget is set to 10 in the Widget parameters. By clicking the gear icon and Parameters, you can select the Table Rows parameter, connecting the Widget parameter to that Page Parameter. Report users can then change the number of rows displayed in the table.

  • The Show Data Labels parameter of the pie chart Widgets can be similarly connected to the previously defined Page Parameter labeled "Show Pie Chart Labels". By connecting both pie chart Widgets this way, the Page Parameter will manipulate both. Report users can then show or hide the pie chart labels.

Configuring the Page Parameters Widget

The final step is to add a Page Parameters - Block Widget to the Page. Recall that you can only have one of these Widgets on a Page. This is the element that provides visual controls for report users. Like other Widgets, this one has its own set of Widget parameters. For this example, they are set as follows:

  • Title: This is some short text to provide a hint for report users. For the example, the Title might be "Your Options For This Report".

  • Page Parameters: Select which of the defined Page Parameters you want report users to be able to see and use. Click the Select button, and in the Select Items dialog, select the Page Parameters the Widget should display for the list of defined Page Parameters.

  • Width: The width (in pixels) of the Widget in the report Page.

After saving the Page, users with permission to read Pages will be able to view the Page and change the Page Parameters in the Widget to alter what they see in the connected Widgets in the Page.

Figure 16.15. End Result of Page Parameters Configuration

End Result of Page Parameters Configuration

Report users now have some interactive options.

Advanced Topics

The visual report building capabilities of Pages are designed to meet the needs of a broad spectrum of users, and to make it easy for non-programmers to build useful reports. Advanced users and developers may wish to implement custom scripting or programming in Pages. Two Widgets are provided for such users:

  • Script - Block: inserts a scripted/coded Widget in the page as a block.

  • Script - Inline: inserts a scripted/coded Widget in the page inline with text.

When one of these Widgets is placed into a Page, the Parameters sidebar opens and displays a simple source code editor where the developer can write or paste source code. Velocity is the recommended scripting language. Macros and $variables are supported.

Security: Best Practices for Pages

Warning!

Poorly written code on a Wiki or LiveDoc ™ (Rich Text) page can leave your system open to XSS (Cross-site scripting) attacks using malicious Work Item and API calls. (Anything, Java code included, can be added to a Work Item in the document and the API will return the actual value of the target fields.)

See Security: Best Practices for details.

Reusing Widgets

A good starting point for custom-scripted widgets may be to reuse an existing widget that is already configured, and modify it with some additional code. You can copy the source code of any existing Widget and paste it into a Script Widget, after which you can begin modifying the code.

To reuse an existing Widget's source code:

  1. Open the page containing the Widget you want to reuse.

  2. On the header of the Widget, click the (Actions) icon and select Copy Widget Source Code.

  3. Add a Script widget to the page and paste the source code from your clipboard into the source editor in the Parameters sidebar.

    You are now ready to modify the Widget source code as desired.

Work Item Properties Sidebar or Drag and Drop Features

To use the Work Item Properties Sidebar or drag and drop features, a unique widget ID must be specified for each item within a selected Script Block..

(See Making Widget's Work for details about these widget features.)

Using a Page Script

Advanced report developers can use the Page Script sidebar of the Report Designer to write a Velocity script which can set values to the $pageContext variable. The page script can use the same context variables as script widgets with following exceptions:

  • Use $renderingContext instead of $widgetContext. It is class RichPageRenderingContext, which has most methods of RichPageWidgetRenderingContext, but not those related to Widgets.

  • $parameters is not available.

This $pageContext variable is then available for all Widgets on the Page, but its value cannot be modified by the Widgets or the UI. Typical usage scenarios include:

  • Prepare data in a Velocity variable and use that variable in Velocity content of different Widgets on the Page (i.e. Script block, or any Widget with a data set), so that they use the same input.

  • Prepare data in a Page parameter and bind that parameter to different Widgets on the Page, so that they use the same input.

  • Define Page parameters via this script which cannot be edited via the user interface.

The following actions are available in the Page Script sidebar:

  • Show Result displays the result of executing the page script, which can be useful for script debugging.

  • Show Log displays errors and warning logged by Velocity during page script execution.

  • full screen at the bottom of the sidebar displays the script editor in full-screen mode. Press Esc to return to sidebar mode.

Notes

The script does not affect any Widgets in the Page until you click the Apply button.

Because rendering of the Widgets may be running concurrently, the objects placed in the $pageContext variable must be thread-safe if accessed by more than one Widget in the Page.

For more detailed usage information and examples, please refer to the Widgets SDK documentation, included with the Polarion SDK.

Organizing Widgets With Tags

Widgets can be tagged by categories and users can easily find Widgets by category. There is set of predefined categories for Polarion Widgets, but widget developers can also set their own categories for Velocity widgets.

Tags for Velocity Widgets are defined in widget.properties via property tags, which can have a comma-separated list of values: tags=Work Items, Planning - for example. Categories are alphabetically sorted, with the exception of "All", which is always first, and "Untagged", which is always last.

Using the SQL Query Type

When you select SQL or SQL + Velocity as the Query Type, an editor displays in the sidebar, and a default SQL query is loaded. Query syntax rendered in grey is not editable. The parts of the statement that you can edit are highlighted in light blue when you click on them. They are just comment lines containing a hint as to what is expected in that specific part of the SQL query.

Note that SQL is generally used only for complex join type queries that, if done with Lucene, tend to impact overall system performance.

Note

If you find that SQL type queries that were working result in errors after you have updated to a new Polarion version, it is probably due to Polarion's transition to a new integrated database. For information about the transition and how to map incompatible queries to the new database, please see the Administrator's Guide topic Database Compatibility (H2, PostgreSQL).

Implementing a Custom Action Button

You may want to provide an easy and visually prominent way for Page users to execute some action that is not provided by any Widget. You can use the Generic Button Widget, found on the Generic tab of the Widgets sidebar. This Widget can be configured to execute an action or open a URL. The latter is a simple matter of entering a valid URL in the Widget's URL parameter. Invoking execution of any other action requires programming in the Click Handler parameter.

Developer Notes for Generic Button:

  • If the Label parameter is empty, the button label defaults to the word Execute.

  • Developers can enter Velocity script and use the Polarion Rendering API in Sub-label, Click Handler and Disable Logic parameters.

  • The Sub-label parameter is optional, and requires script programming. HTML and CSS mark-up are not allowed.

  • The Click Handler parameter is required if the URL parameter is empty.

    You can create builder JsActionsBuilder and call methods to create several objects. Basic syntax: $renderingContext.createJsActionsBuilder(). For more details including actions and parameters see SDK documentation at sdk/doc/javadoc-rendering/com/polarion/alm/shared/api/utils/js/JsActionsBuilder.html.

  • The Disable Logic parameter is a script field like Click Handler, in which a developer can write code to conditionally disable the button. For example, you might want to disable it in historical views. The script returns reason why the button is disabled, which appears in the button tooltip. If the returned value is an empty string, the button is enabled.

  • The Label Color accepts any CSS color, which is rendered in the button label.

  • If the URL parameter is used, the button is clickable in exported PDF. Otherwise, it is disabled in exported PDF.

Rendering Portal Activities

For some Pages or reports, showing a stream of different activities on the page can be useful. The Activity Stream Widget (Generic tab of the Widgets sidebar) makes this very easy to do. You can opt to show one or more types of portal activities on the page by selecting from a list of sources in the Activity Sources parameter. Activity sources include things like Work Items, Builds, Test Runs, etc.

You can show activities from the current project (the default), another project, or entire repository via the Scope parameter.

The Query parameter enables you to enter query to retrieve the activities to display. Activity Source-specific fields are indexed with prefixes. These are the fields to be used in the Query parameter: workitem.type, workitem.id, workitem.revision, job.rootJob, job.name, job.worker, job.info, revision.name, build.tag, build.stamp, build.artifact.groupId, build.artifact.id, build.project.id, testrun.revision, testrun.groupId, testrun.type, testrun.status.

Both user.name and user.id are indexed for each activity.This can be used to limit the activity stream to the activity of a specific user. For example, the Query parameter with value eTestman will return only activities generated by user "eTestman".

To filter activities according to whether or not the indexed field is empty, use HAS_VALUE or NOT HAS_VALUE.

Displaying the Contents of Spaces

You can easily display the contents of any space in any project or in the Repository scope in your Pages. For example, your project might have a space containing some specification Documents, and you want to provide your Page users quick access to them from your Page.

The Space Index Widget renders a table listing the Documents, Pages and Classic Wiki pages currently existing in a space that you select in the Widget parameters. The name of each listed item is a link that opens the item. Keep in mind that users must have permission to read the items. Any items for which a user does not have read permission are skipped and not shown to that user.

The Space Index Widget accesses the same content that is shown on the space's Index page, but renders it somewhat differently. By default, the Widget limits the display to 20 items (configurable), and the items are sorted only according to the date they were last updated, with the most recent listed first.

  • Select the desired scope in the Scope parameter (required). Items for the current project and the Repository are present in the list. To select a different project, click Select and choose the desired project in the dialog.

  • Specify the name of space in the Space Name (ID) parameter (required). This is usually the name that appears in Navigation.

  • In the Show Top Pages parameter (under Advanced) you can optionally change the number of items to show. The default number is 20. Items are sorted by the date they were last updated. To show all items in the space, leave this parameter empty.