Appendix

This Appendix provides supplemental information and documentation of legacy and deprecated features.

Using Classic Wiki

Important Note

Beginning with Polarion version 2015, this feature is replaced by Pages. You should create all new reports and informational pages using that feature, rather than Classic Wiki (formerly called just "Wiki".) Classic Wiki will be supported through the version 2015 release cycle, and possibly longer. If you have any reports or informational pages that you anticipate needing in the long term, you should plan to recreate these using LiveReport or Info Pages.

Polarion features a built-in Wiki where users can create whatever content they need to support their projects and collaboration. There is a default wiki space for the repository, and a default space for each project, created when the project is created. In projects, you can create additional spaces to help organize your content. For example, you might have one space for guidelines, and another for meeting notes. The wiki provides a highly flexible communication medium accessible to everyone with access permissions for Wiki pages. Wiki pages are stored and versioned in the underlying Subversion repository just like any other development artifact.

The Wiki is fully integrated with other features of the platform, so it is quite easy to pull information from other areas such as the Work Items tracker and display it in useful ways in Wiki pages. A robust library of macros is provided that makes it simple to embed complex information. A complete reference for these and as well as Wiki mark-up syntax is provided online in the Wiki Editor.

This chapter explains the major features of the Wiki. Most interaction is fairly standard. If you have used other Wikis you should have no difficulty working with the integrated Wiki, especially if you use the rich-text editor which is available for working with non-scripted Wiki content.

The entry point of each Wiki space is its Home page, which appears in Navigation under the space name the Documents and Pages topic. Within each Wiki space you can add Wiki pages, and/or create additional Wiki spaces, and Wiki pages within those spaces. The Help topics in this section explain how. As you develop pages, you will probably embed links to other pages. In any page, you can find what other pages are linked to the one you are viewing by clicking the Backlinks button on the toolbar (click Expand Toolsto expose the Backlinks section of the page. This section lists all pages linked to the current page and provides links to each one.

Page Types

There are 3 basic types of Wiki pages in Polarion:

  1. Content pages

  2. Portal pages

  3. Active pages

Content pages are analogous to web pages, while Portal pages are analogous to documents. Content pages can contain dynamic content via use of macros (which can make use of queries). Portal pages have content that is essentially static in nature. Active pages contain Velocity or Javascript code and cannot be edited using Rich Text mode.

You can specify a page's type when you edit it in the Wiki editor. See Editing Wiki Pages. The default type for a new page is Content page.

Accessing the Wiki

The Wiki is available in both the Repository scope and project scope.

To access the Wiki:

  1. In the Open Project or Project Group dialog, select either Repository, or select a project, and open the selected scope.

  2. In the Navigation pane, expand the Documents and Pages topic. The Default Space topic appears which gives access to the default Wiki space. If you have created other Wiki spaces, they appear as child topics under the Documents and Pages topic. (Documents also appear in the Documents and Pages Navigation topic.)

Navigating Between Wiki Spaces

When multiple Wiki spaces exist in for the current scope (repository or project), they appear as child topics of the Documents and Pages topic in Navigation. Click any Wiki space name in Navigation to navigate into a different Wiki space. The node expands and the Navigation focus shifts to the Home topic of the Wiki space you selected.

Note that if you click on Default Space, the Navigation shifts to the main Home topic - as the project's Home pages is also the main page of the Default (Wiki) Space.

See also: Creating a New Wiki Space.

Navigating to Wiki Pages

There are two main ways to locate and access Wiki pages: browsing and searching.

Browsing page names in Navigation is available if the space doesn't contain too many pages. In this case, you can just click on the name of a listed page to navigate to it. If there are too many pages to display in Navigation, (generally more than 20), you can click the Too many documents... text in Navigation to load the space's Index page. The Index page provides a table of all the content in the Wiki space in alphabetical order by name. The name of each item in the table is a clickable link to that item. The table in the Index page can be sorted on different columns by clicking on the column headers. The Index topic appears in Navigation when there are not too many items in the space, and you can click it to access the Index page.

When your Wiki contains many pages, searching may be the best way to find what you want. Start at the Search box in Navigation. For information, see Searching the Wiki.

Creating a New Wiki Space

You can create Wiki spaces as needed for different types of discussions and collaboration. You can think of Wiki spaces like folders in other applications, except that they are not hierarchical... that is, you cannot create Wiki spaces inside a Wiki space. In each space, you can create as many pages as you need. (You can also create Documents in spaces.)

To create a new Wiki space:

  1. Open the project in which you want to create a new Wiki space.

  2. In the Navigation pane, select the Documents and Pages topic. The project Wiki's main page appears.

  3. Click the Create button on the page's toolbar and select New Space. The New Space dialog appears.

  4. Enter a title and name for the new Wiki space in the Space Title and Space Name fields, respectively. (Name is the system ID and can contain only ASCII characters.)

  5. Click OK to create the new Wiki space with the title you specified. The new space title appears in Navigation, and the new space's Home page opens with default content, which you can edit and modify.

TIP

Alternative: You can also create a new Wiki space using the New Space item of the Actions menu found on the Home page of all Wiki spaces. Note that spaces created this way are not created as children of the space in which you are currently. Spaces are not hierarchical, so each new space appears at the same level under the Documents and Pages topic in Navigation.

Changing a Space Title

To change the title of a space:

  1. In Navigation, expand the node of the space for which you want to change the title and click on Index.

  2. On the space index page toolbar, click the Actions button, and on the drop-down menu choose Change Space Title.

  3. In the dialog, modify the Title field and click Save.

    Note that the space name cannot be changed because it is the system ID, which cannot be modified. Consequently, you may see significantly different values in the Name and Title fields after changing the space title.

Creating a New Wiki Page

There are 2 ways to add a new Wiki page:

  1. Use the Create New found on the toolbar of each space's Index page, and choose the Classic Wiki Page option.

    It doesn't matter which Wiki Space or Subspace you are in currently when you invoke the Create New operation. You can specify the name of the target Space or Subspace in for the new page in the Create Classic Wiki Page dialog.

  2. Edit any Wiki page and create a link a page name that does not yet exist, and then save the edited page and click the new link.

    If you did not specify a Space or Subspace name in the link, the new page will be created in the same space as the page containing the link. Otherwise, the new page will be created in the specified space.

TIP

When creating a new Wiki page, the Name field is the page's system identifier (ID). It must be unique within the space, and only ASCII characters are allowed.

The  Title field is a human-friendly title that can contain non-ASCII characters. If specified, the value of Title appears in Navigation. (If not specified, the value of Name appears.) You can modify the Title any time using the Change Title action on the wiki editor toolbar.

Creating a New Wiki Page Via a Link

To create a new Wiki page by defining a link to it in an existing page.

  1. Navigate to an existing Wiki page.

  2. Click the Edit button to open the wiki editor.

  3. Enter the name of the page you want to create, enclosed in square brackets. For example: [My New Page].

    If you want the new page created in a specific space, specify the space name in the link: [SpaceA.My New Page].

  4. Click the Save and Close button. A link to the new page, formatted in red font color, now appears on the current Wiki page.

  5. Click on the link to the new page. The new page opens in the Wiki Mark-up editor.

  6. Use the editor to add content to the page and click the Save and Close button when finished.

Creating a Work Item from a Wiki Page

You can use the Extract Work Item feature to create a new Work Item from some selected content in a Wiki page. This is useful when you have been using the Wiki to collaborate on some content like requirements or test cases, and you now want to have these tracked as Work Items so they can be managed with workflow, assigned to people and Time Points, planned and schedules, and so forth.

To extract a Work Item from Wiki content:

  1. Navigate to the wiki page containing the content that you want to extract into a new Work Item.

  2. Select the text in the page that you want to be the description of the new Work Item. The Extract Work Item button is enabled. (Click Expand Tools of the page toolbar is hidden.)

  3. Click the Extract Work Item button. The Select Project and Type for new Work Item dialog appears.

  4. By default the new item will be created in the current project. If you want to create it in a different project, select the project name in the Project list.

  5. Specify the type of the new Work Item by selecting a type in the Type list. The list items are determined by the Work Item types configured in the selected project.

  6. Choose a destination for the new Work Item. By default it will be created in the Tracker (i.e. the Work Items topic). If you want the new item to be created and contained in a Document, choose Create in Document and then select the space and name of the target Document. The Document must already exist... you cannot create a new Document this way.

  7. The new Work Item is created and opened in the Work Item Editor which opens in a frame in the current wiki page. Edit the new item as desired and click the Create button to save it to the repository.

The Title field of the new Work Item is filled in with the first sentence of the selected text, up to first period character, or first 20 words. If there is no period among first 20 words, the entire selection is written into the Description field and you should supply content in the Title field.

After you Save the new Work Item, the Tracker frame disappears. A link to the new item now appears at the point where you began selecting content. You can click this link to navigate to the Work Item in the Work Items topic, Table view. In the Hyperlinks section of the Work Item Editor, you will find a link to the wiki page from which the Work Item was extracted.

Removing a Work Item Link

If at some point you want to remove the generated Work Item link from the wiki page, you can do so by deleting the generated macro using the Wiki Markup editor. In the editor look for {workitem: projectid/workitem-id} where projectid is the ID of the project containing the linked Work Item, and workitem-id is the ID of the linked Work Item. Delete this tag and save the page to remove the link.

The link no longer displays in the wiki page. Only the link is deleted - the Work Item created from the wiki page content (using Extract Work Item) cannot be deleted except in the Tracker or Document (see Deleting Work Items). The Work Item will still contain a link to the wiki page in the Hyperlinks section of the Work Item Editor. You can delete the hyperlink from there if you wish.

Editing Wiki Pages

Once Wiki pages have been created, you can use the Wiki editor to create and modify content. There are 2 options for editing their content:

  • "Wiki Markup", using Wiki syntax (default)

  • "Rich Text" (WYSIWYG)

Information on using each of these options appears in later sections.

Launching the Wiki Editor

Access to editing is hidden by default. Click Expand Tools to expose the wiki page toolbar at the top of the page. Click the Edit button to launch the Wiki editor. The editor opens in the default mode "Wiki Markup", i.e. text-based editing using Wiki syntax.

When you open the Wiki editor, the Rich Text button appears on the button bar at the top of the editor pane. Click this button to switch to Rich Text (WYSIWYG) mode. You can switch back to plain text mode using the Wiki Markup. You can switch between the two modes any time.

Note that pages containing Velocity macros or other scripting do not show the Rick Tex button and cannot be edited in Rich Text mode.

Using Rich Text mode

If you are not familiar with Wiki syntax, the Rich Text mode is a good way to get started creating Wiki content. This mode does not currently support all content creation and editing features however. For example, to add images you must use the plain text (Wiki Markup) mode. You cannot use this mode to enter Velocity, Javascript, or HTML/CSS code. The embedded Wiki syntax help provides information and examples for these and other elements and constructs.

In Rich Text mode you can format text content with graphical controls similar to those found a word processor application. These controls appear on the Rich Text toolbar (shown at the top of the editor pane when Rich Text mode is active). The toolbar currently provides these capabilities:

  • Cut, copy, and paste

  • Undo, redo

  • Text style picker (formats selected or next text as normal or one of several levels of headings).

  • Basic paragraph and heading styles

  • Font for matting: bold, italic, underline, strike-through, superscript, and subscript

  • Insert horizontal rule

  • List formatting: numbered and bulleted

  • Paragraph indent/outdent

  • Insert Link or Plain Wiki syntax

  • Remove existing formatting of selection or entire text

  • Insert table and table operations (enabled after insert)

Linking to Other Content

To create links to other content, you must use the Wiki syntax for links. Rich Text mode provides the possibility to create links to other pages without switching back to Wiki Markup mode. When you click the Internal Link on the editor toolbar, a placeholder link construct is inserted to the page. Please refer to the embedded Wiki Syntax Help that appears when you edit pages.

Adding Attachments

The Attachments section is available in Rich Text mode, enabling you to add or remove attachments to/from the currently edited Wiki page. Note that before you can insert images in text, you must add them as attachments. See Working With Attachments for more information.

Using Wiki Mark-up

This edit mode enables you to format text, create links, display images, and perform other editing operations using standard XWiki syntax. You can also enter Velocity macros and scripting, Javascript, and HTML/CSS code. This text-based editing is the default mode when you click the Edit button in the toolbar of each Wiki page.

Note that in pages that support Rich Text (i.e. they contain no scripting), you can switch between the Wiki Markup and Rich Text (WYSIWYG) mode any time during an editing session. You can use the Preview button to see how your unsaved edits will look in the wiki page after saving.

Using Wiki Syntax Help

The Wiki Syntax Help link appears at the right-hand side of the screen when the Wiki editor is active in Wiki Mark-up mode.

The panel displays a number of labeled bars which represent different Help topics. The categories are for different document elements, formatting, and macros for embedding tracker and other dynamic content in wiki pages.

Clicking on any of the category bars expands it to reveal the syntax Help for the selected category.

This embedded help provides basic help for most editing tasks. More comprehensive syntax help is provided in a special wiki page. To access this page, look for the Detailed Syntax Help link at the bottom of the embedded syntax help in the Wiki editor. You can bookmark that page in your browser for future reference.

Displaying Images

You can display images in Wiki pages after they have been uploaded as attachments. Use the Attachments section to upload your image file(s) and save the page. Then use the "Insert placeholder {image}" button on the toolbar to insert the syntax for an image reference at the desired place in your text. Replace image-attachment-filename.ext in the inserted {image} macro with the file name and extension of an attached image.

Creating Tables

The {table} macro renders a table in the Wiki page. Table rows and columns are defined between two {table} elements. Each line represents a row. Columns are separated by a vertical bar character (|). The first line may be optionally defined as the table header.

Various parameters of the {table} macro provide control over some formatting. The id parameter, if specified, causes the value to be rendered in the "id" attribute of the table's HTML. This can be subsequently referenced in scripting.

For more specific information, consult the Tables section of the Wiki Syntax Help in the Wiki editor.

Working with Attachments

You can attach files of any type to a Wiki page in the Attachments section. The page section is hidden by default when you are reading a page. When hidden, or if visible but scrolled out of view, you can jump directly to it by clicking the Attachments button on the Wiki page toolbar. Graphical controls are provided for adding and removing attachments.

After attachments have been added to a Wiki page, you can see their links in the page and optionally download them to your local system. Images must be uploaded as attachments before they can be displayed in the page content.

By default, the maximum file size of attachments is limited to 50 MB. The limit is configurable in Administration.

See also: Wiki History - Download Attachments from a Revision.

Adding an Attachment to a Wiki Page

To add an attachment to a Wiki page:

  1. When viewing (i.e. not editing) a Wiki page, click the Expand Tools > Attachments to expose the Attachments section. Any existing attachments are listed in a table.

  2. Click the (Edit) icon at the bottom left corner of the Attachments section. The graphical controls to add an attachment appear.

  3. Enter a title for the attachment. (Spaces not allowed.)

  4. In the File Name column, click the Browse button and navigate to the file you want to attach.

  5. If you want to add another attachment, click the icon in the same row and repeat the previous step.

  6. After adding all attachments, click the Save icon.

Note

Your system or project administrator can optionally limit attachment file size. Contact your administrator if you are unable to upload an attachment due to such restriction.

Updating an Existing Attachment on a Wiki Page

You can update an existing attachment in the Wiki Markup editor or the Rich Text editor. You do this by adding an attachment in the Attachments section of the editor and checking the Update existing attachment option on the row of the new attachment. The file you upload for the new attachment must have the same file name and extension as the existing attachment you want to update.

Removing an Attachment from a Wiki Page

If an attachment is no longer needed, it can be removed from a Wiki page. In the table of attachments in the Attachments section, click the icon on the row of the attachment you wish to remove. The attachment is removed from the page when you save the change. It still exists in the page's history and can be accessed there.

Downloading an Attachment from a Wiki Page

In the Attachments section, locate the attachment you want to download in the table of attachments. The file name of the attachment appears as a link in the File Name column. To download the file, right click on the file name and choose the command that saves a remote file to your local system. For example, in Firefox choose Save Link As.

Adding 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 = 'playground'}
                        

Note that 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 the User Guide topic Constructing 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 {toc} 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 Administrator's Guide: Advanced Administration: Advanced System Tuning: Properties for Activity Stream.

Using 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 Searching 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.

Referencing 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 that 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).

Displaying 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).

Extending Wiki Pages with Velocity

Read-only:

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 Administration Reference: Velocity Variables for Active Wiki Pages.

Creating Interactive Report Pages

All except

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.

Creating Charts in Wiki Pages

Polarion integrates the Highcharts library, which enables users to easily create and show various types of simple and complex charts in wiki pages, including Dashboards. You can implement these charts using special Highcharts code. Chart types are documented with examples in the embedded Wiki Highcharts Help. You can access this help via the embedded Syntax Help in the Wiki Mark-up Editor, or directly by its URL in your Polarion portal.

To access Highcharts help via the Wiki Syntax Help:

  1. Open any Wiki page for editing.

  2. In the Wiki Syntax Help panel, click the Wiki Highcharts Help link at the bottom of the panel.

Alternatively, you can go directly to the Wiki Highcharts Help on your system using this URL:

http://[HOST SERVER].[DOMAIN]/polarion/#/wiki/Doc/HighchartsHelp

... where [HOST SERVER] is the name of your Polarion server, and [DOMAIN] is your internet domain. Example: http://polarion1.yourdomain.com/polarion/#/wiki/Doc/HighchartsHelp

See also: Administrator's Guide, Configuring Highcharts Export.

Exporting Wiki Content to PDF

You can export the content of Wiki pages to Portable Document Format (PDF). During the export operation you can set options for page size, orientation, fitting output to page, bookmark generation, and inclusion of a header and footer. You can save the generated PDF to any accessible storage (local or network).

The content of the header and footer in generated PDF documents is configurable in Administration, either globally for the repository, or for a specific project. Headers/footers can include such information as the page name, history revision number, creator's user name, the export date, current page number and total number of pages (e.g. 7/20). For information, see Administrators Guide: Configuring Documents and Pages: Configuring PDF Export.

TIP

The configuration for PDF headers/footers changed significantly in Polarion 2011. If you update from an earlier version in which you configured PDF export for wiki pages, you will need to reconfigure it in your current installation. See Administrators Guide: Configuring Documents and Pages: Configuring PDF Export.

To export a Wiki page to PDF:

  1. Navigate to the Wiki page you want to export.

  2. In the page toolbar, click the Actions button and select Export to PDF on the drop-down menu. The Export to PDF dialog appears.

  3. In the dialog, select the desired options for the PDF document, and click Export.

    TIP

    You can change the settings and quickly re-export the same page until you close the dialog.

  4. Save or open the exported PDF according to options presented by your computer's operating system.

Tip

You can export any historical revision of a Wiki page to PDF. The procedure is basically the same as for a Wiki page (i.e. find the export action in the Actions button menu), except that you must first open the page's History and open the desired revision by clicking on the revision number.

Printing a Wiki Page

You can print the current Wiki page to any accessible printer. To print the current page:

  1. Click the Actions button on the Wiki page's toolbar.

  2. On the drop-down menu, select Print. The Print dialog appears.

  3. Wait for the printer-friendly version of the page to fully load in the Print dialog, then click the Print button in the dialog. Your operating system's Print dialog appears.

  4. In the operating system Print dialog, select the target printer device, set print properties if needed, specify the output file name, and launch the print job.

  5. Close the Polarion Print dialog using the close control in the title bar.

Searching the Wiki

It can be faster to locate Wiki pages using the Search field at the top of the Navigation pane. However, you need to have some idea of the page name you want to access... at least the first several characters. Typing in the Filter box starts an incremental search of all the content in the project. You can limit the search to the Wiki. After typing one or more characters in the Search field, the Navigation panel presents options for limiting search to different types of content.

Using Global Search

You can also search for Wiki content using the global search. Type some text in the Search field and press your Enter or Return key. In the search results page, click the Wiki link to filter the results for Wiki pages only.

The search results page provides controls to refine your search or start a new search.

Working with Wiki History

The Polarion Wiki uses the underlying Subversion repository to store Wiki content. Consequently, the content is versioned and history is maintained just as with other artifacts in the system.

This section covers basic operations with Wiki history.

Finding a Specific Revision

Each time a Wiki page is changed and saved, a revision is created in the repository and added to the history.

To see the history of any Wiki page:

  1. Navigate to the space and the page.

  2. Click on the History toggle which appears on the page toolbar.

The History shows all revisions of the current page. There you can access any revision of the page, compare revisions, roll back changes, and access revisions of any attachments.

Revisions are listed by revision number. Revision numbers are clickable, and lead to the specific revision of the page, including any attachments, links, etc. Revision numbers will not necessarily be sequential, as they are for the repository as a whole, not for the specific Wiki page. The most recent revision appears first in the table.

Comparing Wiki Page Revisions

To compare two Wiki page revisions in History:

  1. Navigate to the Wiki page whose revisions you want to compare and click the History toggle button in the page toolbar to show the table of revisions.

  2. In the left-hand column, check the boxes on the rows of the two revisions you wan to compare. (You can only check two boxes at a time.)

  3. Click the Compare button at the top of the page. The comparison page loads in your browser.

The page displays counts of things that were added, changed or deleted between the earlier and the later of the two revisions being compared. Two buttons labeled Previous and Next enable you to navigate among the changes in the page, enabling you to easily see what changed and how.

Three buttons at the top of the page enable you to select different views of the comparison. The default is Page. When selected, you see the what the compared pages actually look like in the wiki. The Source shows you the underlying wiki markup language, enabling you to compare changes that occurred there which might not necessarily reflect when the Wiki page is viewed. The Attachments button enables you to compare the attachments to the two revisions.

Exiting History Comparison

When you are comparing to Wiki page revisions, the Back to History button appears at the top above the two revisions. Click it to exit the comparison and return to the table of revisions on the History view of the page.

Rolling Back Changes

You can roll back the changes made in any revision of any Wiki page.

To roll back changes made in a revision:

  1. Navigate to the desired Wiki page.

  2. Click the History toggle button on the page toolbar.

  3. In the table of revisions, locate the revision you want to roll back.

  4. Click the Rollback link in the Action column.

Downloading Attachments from a Revision

Each revision of a Wiki page contains a version of any attachments. If attachments are added, removed, or updated, a new revision of the page is created in the repository which includes the attachments current at the time of the revision. Revisions of any Wiki page are shown in its History (see Finding a Specific Revision).

To access the attachments for a specific revision, open the revision in the history (click on the revision number), click the Attachments button in the Wiki page toolbar, and locate the attachment in the Attachments section. Right click on the desired attachment and use the save link command on your browser's right-click menu to download and save the attachment to your local system.

Using the Activity Stream

If the page author has included the {activity-stream} macro in the page mark-up, the portal Activity Stream appears on the page. The Activity Stream is similar to the news feed feature found on many social media websites. It displays a stream of activities taking place on the Polarion portal. Activities may have different sources such as builds, or Work Items. Some pages contain the Activity Stream by default: the portal Home page, and users' "My Polarion" pages, for example.

Each activity in the stream displays some basic summary information such as the name of the user who triggered the activity, and when the activity took place. Hovering over an activity highlights it, and clicking on it (or on the Show More link, if present) expands the activity to show more detail. Each activity contains a link to the activity source... a Work Item, build, or commit, for example. Clicking the link takes you directly to the source item.

If the activity source is a Work Item, you can post a comment directly in the activity in the Activity Stream by clicking the Add Comment link. You must have permissions for the project which allow you to write and save comments in Work Items. If you don't, you will see a message when you try to save the comment using the Save Comment link.

The activity stream is refreshed when the wiki page containing it loads or reloads. You can explicitly refresh the stream to see new activities using the (Refresh) icon at the top of the activities.

Searching the Activity Stream

You can enter a search query in the provided field to filter the activities listed in the stream. For example, you might search for all items containing a word or words, or for specific types of activity.

Full-text Search

The simplest and most intuitive way to search the Activity Stream is to enter some word or words. The results will show all activities (if any) that contain the search string. If the search string is a user name, the results will contain both activities generated by the user, and activities containing the name somewhere in the content.

If you enter multiple words, the search logic is "AND". So for example, if you search for "smith language", the query logic is "smith AND language". The results will contain activities generated by any user named Smith, activities mentioning "smith", and activities mentioning "language". You could specify the AND operator, but it is not required. If you want to exclude some term, you can precede it with the operators AND NOT. For example: "smith AND NOT language".

If you enter multiple words and you want results with one or the other, you can enter the OR operator: "smith OR language".

Search by Activity Source and Type

You can search for a specific stream source and type by entering a query in this format: sourceId:[ID]. For example, you could filter for activities around Work Items with this query: sourceId:workitems.

You can refine the filter by including the type parameter in the filter query. For example, you could filter for activities around Work Items which are updated with this query: sourceId:workitems AND type:updated.

You can also enter values for an activity type like "updated" or "created" or "build" to search for activities with that activity type. You can use AND/OR logic to search on multiple types, or keywords and types: a user name and "created" type activities, for example.

For complete information on the activity sources and types that you can query for, see User Reference: Activity Stream Sources and Types.

Wiki Administration Operations

As is usual with Wikis, users can update pages including updating of content and performing administrative operations such as adding Wiki spaces and adding Wiki pages, and also deleting spaces and deleting pages. However, in Polarion users must have permissions for these actions in the scope in which the perform the actions (project, project group, or repository).

Deleting a Wiki Page

To delete a Wiki page:

  1. Navigate to the page you want to delete so that you are viewing it.

  2. Click the Actions button in the toolbar and choose Delete on the drop-down menu.

  3. Respond Yes to the confirmation prompt.

TIP

You can also delete a Wiki page from the Index page of the space in which the page resides. Check the box next to the name of the page(s) you want to delete, and click the Delete button on the Index page tool bar.

Deleting a Wiki Space

To delete a Wiki space:

  1. In the Documents and Pages topic in Navigation, select the space you want to delete and then navigate to its Index page.

  2. In the toolbar of the Index page, click the drop-down actions menu (displays a gear icon) and choose Delete Space.

  3. Respond Yes to the confirmation prompt.