Add Dynamic content in Wiki Pages

The wiki has a number of macros that can be embedded in wiki pages using the Wiki Markup editor. Some macros merely provide formatting - the {code} macro for example. Others provide content structures such as tables, or display an image. Still others provide content from the tracker or the system which is dynamically retrieved, formatted, and displayed in a wiki page. Such dynamic content may include subsets of Work Items, or information about project users, or links to other projects and their wiki content.

This section covers several of the most commonly needed macros. The full listing is provided in the embedded Wiki Syntax Help, accessible from the Wiki editor.

The {project} macro

The {project} macro can be used to get a link to Polarion project. You can find more details and usage examples in the Projects topic in the Wiki Syntax Help, available in the Wiki editor while editing a wiki page.

The {workitem} and {workitems} macros

The {workitem} and {workitems} macros can be used to extract information about, and create links to Work Items. The {workitem} macro retrieves a single item. {workitems} retrieves multiple items. The content returned, and the format, can be controlled via several parameters, including a parameter that can contain a simple or complex Lucene query, and a parameter than can contain a SQL query (see next section). You can find more details and usage examples in the Work Items topic in the Wiki Syntax Help, available in the Wiki editor while editing a wiki page.

Using SQL queries to retrieve Work Items:

Polarion has an embedded SQL database layer that can facilitate Work Item queries in traceability reports and other complex reports in Wiki pages where a Lucene query would be highly inefficient and consume undue time and system resources, or not work at all. For example, you could not readily formulate an outer join in Lucene, but it's easily done with SQL. Primary storage of artifact data remains in the Subversion repository, but the SQL layer maintains a special read-only index of the content which can be queried in the {workitems} macro. Results of the SQL query can be read by all users using any product license (assuming they have read permissions for project wiki pages).

You can include the sqlQuery parameter in the {workitems} macro to execute a SQL query over Work Items. When this parameter is used, other parameters that can also be used in the macro are limited to:

```
display
```
```
expand
```
```
top
```
```
fields
```
```
width
```
```
height
```

EXAMPLE:

{workitems: sqlQuery=
 SELECT WI.C_URI
    FROM WORKITEM WI, PROJECT P
 WHERE WI.FK_URI_PROJECT = P.C_URI
    AND P.C_ID = 'drivepilot'}

(Will work on the Drive Pilot demo project. Replace drivepilot with your Project ID to try it there.)

Note:

If a query's processing exceeds limits set in the system configuration, it may be halted, and a notification sent to the system administrator in order to prevent other users updates from being blocked by long-running queries.

Tip:

The graphical Query Builder in the Work Items topic contains an element SQL. It can be used alone to filter the Work Items table by a SQL query only, or in conjunction with other visual query elements. As with all Query Builder queries, the visual query is transformed to a URL, and can optionally be converted to text via the Query Builder's drop-down menu.

The SQL element can be useful if you want to open result of the {workitems} macro filtered by the sqlQuery parameter in the Work Items table, instead of entering a fully expanded query with IDs. For more information on using the graphical Query Builder, see Construct Queries Graphically.

The {users} macro

The {users} macro returns a list of users for a specified project. The content returned can be controlled via several parameters, including a parameter that can contain a simple or complex query. You can find more details and usage examples in the Users topic in the Wiki Syntax Help, available in the Wiki editor while editing a wiki page.

The {toc} (Table of Contents) macro

The macro generates a table of content based on the headings in a wiki page. The content returned can be controlled via several parameters. You can find more details and usage examples in the Headings topic in the Wiki Syntax Help, available in the Wiki editor while editing a wiki page.

The {import-automated-test-results} macro

The {import-automated-test-results} macro embedded in a wiki page enables page users to launch import of automated test results from any wiki page, not just Test Run pages. In regular wiki pages, the testrun parameter must be specified. Complete information on parameters is provided in the Wiki Syntax Help, available in the Wiki editor.

The {pages} macro

This macro renders a list of pages in a project or project group. For parameters and example, see the Pages topic in the embedded Wiki Syntax Help in the Wiki editor.

The {activity-stream macro}

This macro displays the stream of activity which has occurred on your Polarion portal. The activity stream is similar to the news feed feature on social media sites. The macro's parameter enable you to restrict the amount of information displayed. For details, see the Activity Stream topic in the embedded Wiki Syntax Help in the Wiki editor.

Users of wiki pages displaying the activity stream can enter a query to filter the stream to restrict the display to some specific information... some user's activity, or build activity, or a date, or date range for example. Users can optionally click the provided link to display the Activity Stream page which not only shows the stream and filtering, but provides quick links to filter for commonly needed stream information.

Administrators can tune the system configuration to control the age and/or number of activities maintained in the history. See: Properties for Activity Stream.

Use queries in macros

Macros such as {workitems} provide a parameter query in which you can specify a simple or complex query to retrieve data. The query syntax can be copied from a visually constructed query in the Query Builder, found in the Table and several other views in the Work Items topic. (See Search Work Items). For example, you can use the {workitems} macro to display a listing of unresolved blocker and critical defects on a wiki page by specifying a query as shown in the following listing:

{workitems: query=NOT HAS_VALUE:resolution AND type:defect AND (severity:blocker OR severity:critical)}

You can use the Query Builder to construct the query and then copy the query parameter shown in the page URL into the macro's query parameter.

Reference fields in queries

Queries can specify which fields should be displayed in the results by including the fields in the query. For example, the following query will display only the Work Item ID, Title, and Severity fields in the results:

{workitems: query=resolution:fixed AND type:defect | fields=id, title, severity}

Note:

the fields parameter must reference field ID, not field label. Field IDs are case sensitive and do not contain spaces. For example, for the field that logs time spent on a Work Item, a macro query must specify time_spent (the field ID), and not Time Spent (the field label).

The same is true in the sortby parameter which specifies on which field the results should be sorted: specify the field ID, not field label. Example:

{workitems: query=resolution:fixed AND type:defect | fields=id, title, severity | sortby=severity}

The rule of thumb is that any macro parameter that references one of more Work Item fields must contain field ID(s), not field name(s).

Display charts in Wiki Pages

Polarion includes the FusionCharts free library that provides many types of charts. Usage is outside the scope of Polarion documentation, but the library's documentation is bundled into distributions. You can find a link to it in the Dashboard topic of the Wiki Syntax Help (accessible when any Wiki page is in edit mode).

Extend Wiki Pages with Velocity

Read-only with (REV licenses.)

Users of the Polarion Java API can extend active wiki pages by means of Apache Velocity (see http://velocity.apache.org/engine/1.4/user-guide.html). For information about Velocity variables available via the API, see: Velocity Variables for Active Wiki Pages.

Create interactive Report Pages

All except: (REV licenses.)

A major use case for dynamic-content wiki pages is reporting. For example, a page can be created to show all unresolved critical-severity items for some time point. That can be useful, but what if a report consumer wants to see unresolved critical-severity items for different time points, or assigned to different users?

It is possible, of course, to create separate pages, or separate sections in pages to report on each different set of parameters. But it would be more useful to enable the report consumer to interactively change some key parameters using simple graphical controls and obtain variant results. Polarion provides this functionality through a set of parameterization macros. Users who know how to code wiki pages can easily create report pages for less technical users, enabling them to create variant output for the same basic report, which they can optionally export to PDF just as with any wiki page.

Parameter Macros:

Polarion provides the set of parameter* macros which enable you to create interactive report pages:

{parameter} - declares a parameter of a specified type and value(s) which can be referenced in other elements on the page.
{parameter-form} - declares the start and end of an interactive part of the page which displays interactive "widgets" or controls rendered by other macros of this group.
{parameter-editor} - displays an edit control in which user can edit the value(s) declared in a {parameter} statement.
{parameter-form-submit} - provides a button widget for submitting user changes to one or more {parameter-editor}s. This macro is available in Baselines.
{parameter-form-save} - provides a button widget for saving user changes to one or more {parameter-editor}s, overwriting current values in the respective{parameter} declaration(s) in the page source.

The {parameter} and {parameter-editor} macros take one or more arguments. The complete syntax reference is provided in the embedded Wiki Syntax Help (click Detailed Syntax Help at the bottom of the Syntax Help pane in the Wiki Editor).

Basic Parameter Usage:

The {parameter} macro enables you to define a parameter which can be subsequently referenced in other page elements... in the query argument of a {workitems} macro, or the id argument of a {parameter-editor} macro.

You should declare all the {parameter}s for the page first, before any other page content.

##Page Parameter Declarations:
{parameter:myParam1|type=string|value=aaa|allowed-values=aaa,bbb,ccc}
{parameter:myParam2|type=user|value=cJames,kRoth|multi=true}
{parameter:query|type=string|value=type:defect}
{parameter:dateFrom|type=date|value=2011-05-05}
{parameter:dateTo|type=date|value=@current}

You can then reference any declared parameter by appending its ID to the $pageParameters variable following a period character (".") delimiter.

Examples:

Updated from {parameter-editor:dateFrom} to {parameter-editor:dateTo}
...
{workitems:query=$pageParameters.query $!queryOpen AND assignee.id:($pageParameters.getAsString($pageParameters.user, " OR ")) AND 
updated:[$pageParameters.getDateForQuery("dateFrom")TO $pageParameters.getDateForQuery("dateTo")]}

Here is an example of a report page reporting on Work Items with user-selectable team, Work Item type, resolution, and Work Item update dates:

##Parameter Definitions
{parameter:team|type=string|value=teamX|allowed-values=teamX,teamY}
{parameter:query|type=string|value=type:defect}
{parameter:justOpen|type=boolean|value=true}
{parameter:teamX|type=user|value=mTest,aSeller|multi=true}
{parameter:teamY|type=user|value=sDeveloper,pGUI|multi=true}
{parameter:dateFrom|type=date|value=2011-05-05}
{parameter:dateTo|type=date|value=@current}

1 Work Items By Team

{parameter-form}
Select Team: {parameter-editor:team} \\
Query: {parameter-editor:query} {parameter-form-submit} \\
Not Resolved: {parameter-editor:justOpen} \\
Updated from {parameter-editor:dateFrom} to {parameter-editor:dateTo} \\
{parameter-form}


Team members: $pageParameters.render($pageParameters.team,", ")

#if ($pageParameters.justOpen)
#set($queryOpen = " AND NOT HAS_VALUE:resolution")
#end

{workitems:query=$pageParameters.query $!queryOpen AND assignee.id:($pageParameters.getAsString($pageParameters.team, " OR ")) 
   AND updated:[$pageParameters.getDateForQuery("dateFrom") TO $pageParameters.getDateForQuery("dateTo")]}

For more examples, review the E-Library project that ships with all Polarion products. You can open it like any other project, assuming that your administrator opted to install sample date when installing your Polarion system.