18. Advanced Administration


This chapter covers several administration topics of an "advanced" nature that may not always be essential for the setup and maintenance of a Polarion system, but which may be useful in achieving optimal benefits.

System and Virtual Machine Memory

Issues around server memory allocation and Java virtual machine are covered in the PDF installation guide documents bundled with Polarion distributions, and also available for download on the Polarion Software web site:

  • Windows Installation Guide

  • Linux Installation Guide

  • Polarion Enterprise Setup Guide (for users running Polarion on multiple physical and/or virtual servers with one or more Polarion repositories in the topography.)

Administrators of Windows installations should follow the recommendations in the section Adjusting Server Memory Allocation in the Windows Installation Guide.

Administrators of Windows or Linux installations should note the section Java Virtual Machine Memory Limit in the installation guide for their respective OS.

Administrators of clustered server installations should note the recommendations in the installation guide for the operating system on their servers, well as any relevant instruction in the Polarion Enterprise Setup Guide.

The information in these documents can help avoid issues such as startup failure (where the Polarion service does not start) and Java Out of Memory (OOM) errors.

Optimizing the PostgreSQL Database

Beginning with version 2015 SR2, Polarion integrates the PostgreSQL database in all new installations. This system component is used to improve performance on complex system queries. Automated installers for Linux and Windows attempt to modify default PostgreSQL settings to optimize it for operation with Polarion. Assuming the process succeeds, PostgreSQL should perform adequately in most cases. An administrator may optionally adjust the settings described later in this section to better match the specific environment.

If PostgreSQL optimization fails during automated installation, or if Polarion is installed manually (as can be the case with Linux in particular), the administrator should modify PostgreSQL settings as described below to optimize it for Polarion.

The PosgreSQL configuration file is named postgresql.conf, located on path /opt/polarion/data/postgres-data/ on Linux, or C:\Polarion\data\postgres-data\postgresql.conf on Windows. Open the file in any text editor and set the properties as shown in the following listing:

max_connections = 80  # should be less than 10 * number of CPUs
shared_buffers = 2GB # should be 10% - 15% of total system RAM
work_mem = 10MB # should be 10MB - 100MB
maintenance_work_mem = 200MB

fsync = off
synchronous_commit = off
full_page_writes = off

wal_buffers = 256kB   # should be more than size of common transaction

checkpoint_segments = 32

effective_cache_size = 4GB       # should be approx 1/3 of RAM for PostgreSQL

max_locks_per_transaction = 100  # specific for Polarion

# Optimal planner performance setting
# For HDD, keep default setting. Otherwise, uncomment the applicable setting below:
# For SSD: 
# random_page_cost = 1.5
# For SAN:
# random_page_cost = 2.0

After saving the changes, restart PostgreSQL.

Database Compatibility (H2, PostgreSQL)

Polarion replaced the integrated H2 database with PostgreSQL - in new installations only from version 2015 SR2, and in existing installations from version 2016. The database is used for complex query processing, such as are often needed for reports. Users of prior versions may have some report queries formulated for H2 that do not work with PostgreSQL due to its more strictly ANSI-compliant syntax. To mitigate such problems, Polarion provides a database compatibility mode.

Compatibility mode is enabled via the system property com.polarion.platform.sql.h2CompatibilityMode. When set to true, Polarion attempts to adjust queries formulated with H2 syntax "on the fly" so that they work with PostgreSQL. Compatibility mode handles situations where a problematic query cannot be updated to be PostgreSQL compliant - reports in History and Baselines that fail due to missing or incompatible functions, for example.

If, after your system is updated to use PostgreSQL, you find that some queries are not working, enable database compatibility mode. Open the system configuration file polarion.properties in a text editor and make sure the following is present: com.polarion.platform.sql.h2CompatibilityMode=true. Restart the Polarion server to effect the change.

Issues handled in compatibility mode include:

  • Error: Subquery in FROM must have an alias

  • Usage of H2-specific functions that result in errors such as: function curdate() does not exist.

Even when database compatibility mode is enabled, it is still possible that some reports may need to have their queries modified manually.

Mapping H2 Functions to PostgreSQL

This section explains how to map queries that use H2-specific functions to PostgreSQL. (You can find a listing of all H2 functions at: http://www.h2database.com/html/functions.html.)

Here is an example of an error, thrown when the proper curdate function is not defined: "ERROR: function CURDATE() does not exist Hint: No function matches the given name and argument types. You might need to add explicit type casts."

To map a function from H2 to PostgreSQL:

  1. In your installation's file system, navigate to [POLARION_HOME]/polarion/plugins/com.polarion.platform.sql_*

  2. Copy the file h2_functions_mapping.sql, paste it to folder [POLARION_HOME]/polarion/configuration, and open it using a text or SQL editor application.

  3. If the function does not already exist in this file, add your own definition of the function from H2. For example:

    returns date AS
    $$ SELECT current_date $$ LANGUAGE SQL;

    Function definitions must always end with a semicolon (;) to be successfully deployed, and always prefix the names of mapped functions with the schema name polarion, otherwise Polarion will not always take them into consideration.

  4. Enable the property com.polarion.platform.sql.h2CompatibilityMode=true in the polarion.properties configuration file.

  5. Restart the Polarion server.


For easy debugging before deploying a function to the h2_functions_mapping.sql file, try to manually create it in the PostgreSQL database. Use the psql utility to connect to the polarion database as the polarion user: psql -p 5433 -U polarion polarion.

For information on creating PostgreSQL functions, see http://www.postgresql.org/docs/current/static/sql-createfunction.html. To check the definition of a function had in H2, see http://www.h2database.com/html/functions.html.

PostgreSQL Database Start-Stop-Restart

Polarion includes the embedded PostgreSQL database to process complex queries more efficiently than is possible with the Lucene query engine. There may be times when an administrator needs to start, stop, or restart the database.

On Windows, shortcuts are provided in the folder [POLARION_HOME]\polarion shortcuts. On Linux, the following scripts are available:

CentOS, RHEL, Debian

service postgresql-polarion start
service postgresql-polarion stop
service postgresql-polarion status
service postgresql-polarion restart


rcpostgresql-polarion start
rcpostgresql-polarion stop
rcpostgresql-polarion status
rcpostgresql-polarion restart


service postgresql-polarion start
service postgresql-polarion stop
service postgresql-polarion status
service postgresql-polarion restart

Managing Polarion Licenses

Your Polarion server may host more than one license type: named and concurrent, for example. For named user licenses, you need to specify the user IDs of all users who will utilize each named license. For concurrent licenses, you may want to limit the number of users who can access the portal concurrently (the maximum is controlled by the license), and/or you may want to define groups of concurrent users with different limits. You may also wish to check the current usage of your license(s).

You can manage licenses and view current license usage in the Polarion portal. The configuration is only accessible in the repository scope.

Accessing License Management

To access the license management configuration:

  1. Log in with administrator permissions for the repository.

  2. If you are not in the Administration interface after you log in, click the Administration link in the tool view of Navigation.

  3. If you are in a project after you log in, click Global Administration at the top of the Navigation panel.

  4. In Navigation, click on the License topic. The License page loads.

The portal page contains embedded "Quick Help" providing more detailed information on how to use the various license management features.

Specifying License Assignments

The License page provides a plain text editor in the Assignments section which enables you to edit the underlying configuration file, which is named users in the file system. Please refer to the Quick Help documentation on the License Assignment and Usage page of Administration for specifics.

When you change any text in the online text editor, the Save button is enabled which saves changes made in the portal to the configuration file.

Users not named in the license configuration are treated as concurrent users, and will utilize the default concurrent license specified in the configuration. If the default concurrent license is not specified, then these users will use the "highest" license having an unlimited number of concurrent users. If all are limited, then these users will use the "lowest" license with the highest number of concurrent users. If all licenses have zero, then these users will not be assigned a license and will not be able to log in.

Optionally, you can configure that all users who log into Polarion are automatically assigned a concurrent add-on license together with their basic license. If no concurrent add-on license is available, none will be assigned and users can still log in with the basic license. (See the embedded Quick Help on the License page in global Administration.)


The license assignment configuration can be changed only once in 20 minutes.

Viewing License Usage

The License page provides sections that display statistics on how users are currently consuming the licenses available on your Polarion system. The numbers are current as of the moment you invoked the page. Refresh your browser to see any change.

For information about the usage details displayed on the page, see Administration Reference: License Usage Reference.

Updating and Reactivating Licenses

If your organization has purchased new, or obtained updated licenses for your Polarion installation, you can update the installation from the License page in Administration. Use the Reactivate Polarion button to begin the process. You will be taken to the first screen of the activation application, where you will find instructions for activating your license(s) online or offline.

A confirmation dialog appears on each online activation, before the activation request is actually sent. You must confirm that no running Polarion instance is activated by the License Key you are activating.

Configuring Single Sign-on (SSO)

Polarion supports access by users who are already authenticated on the network. The "normal" login page is bypassed for such users. SSO functionality is disabled by default. To enable it, an administrator must configure several system properties in Polarion, and set up a proxy configuration in Apache. When SSO is enabled:

  • Polarion will not display the regular authentication (login) page if user credentials are provided in the HTTP request header (including the first request).

  • When Polarion recognizes user credentials in the HTTP request, it passes the user name and a predefined password to Apache, skipping display of the regular login page.

  • In case of CAC, even an encrypted password is included, which may be passed to Apache to be authenticated through AD/LDAP.

  • If authentication fails, as might occur if there are not enough concurrent licenses, for example, a message (optionally customizable) is displayed to the end user.

  • Users logged in via SSO may log out, thereby freeing up concurrent license slots. On logout, such users are directed to a special page (that is, they are not shown the normal, non-SSO login page).


SSO support is provided only in Polarion version 2011-SR1 and later.

A prerequisite for enabling SSO functionality in Polarion is a reverse proxy configuration in your web server environment which fills headers, so that Polarion can use the headers supplied by the proxy. Such a configuration commonly exists in Apache-based environments, and is outside the scope of Polarion Help. You should check with your web server system administrator to make sure the necessary reverse proxy exists and can be accessed by Polarion. An example Apache configuration for testing purposes is provided later in this section.

Configuring Polarion

Make sure your Polarion server is accessible via http://<polarionservername>/polarion from any client. That is, Apache should NOT bind to localhost only, but to or the server computer's public IP address. Add the following lines into the system properties file polarion.properties:


The usesProxySSO property enables SSO features in Polarion.

userheader and pwheader (required) can be any value. They are just named for the respective headers.

You can optionally add the following property:

login.proxySSOLoginFailed=Message for end users in case authentication fails or is misconfigured.

Reverse Proxy Example

This section provides an example of a reverse proxy configuration for Apache. This configuration is not intended for production use. It is intended only to assist Polarion administrators to test whether SSO is working.

Locate the file named proxy.conf in your Apache installation in directory conf.d (Linux) or conf/extra (Windows). If not already present, create this file.

Open the file in a text editor application and add the following lines in which <polarionservername> is the name of your Polarion server, and <proxyservername> is the name of your Apache server:

# Needed when the proxied host uses https protocol
#SSLProxyEngine On

<Location /polarion>
ProxyPass http://<polarionservername>/polarion  
ProxyPassReverse http://<polarionservername>/polarion
RewriteEngine On
RewriteRule ^/$ http://<proxyservername>/polarion/

RequestHeader append userheader "[username]"
RequestHeader append pwheader "[password]"


Where userheader and pwheader are the values of the header names set in polarion.properties.

Where [username] and [password] are the credentials of the polarion user.

After restarting Apache and Polarion, all requests to http://<proxyservername>/polarion will be forwarded to http://<polarionservername>/polarion, and request headers userheader, and pwheader will be added to these requests, meaning that all requests to Polarion from this reverse proxy are done on behalf of user specified in [username].

Repository Access Management

Polarion utilizes an integrated Subversion repository to manage all data artifacts. Access to Subversion is controlled by the Subversion access file. Polarion provides a web based client with an interface to facilitate administrators who need to control repository access directly in Subversion. This topic explains how to locate and use the client. Subversion administration and access file management is a topic beyond the scope of Polarion Help. Basic knowledge of the SVN access file is assumed. For information about Subversion repository administration, see http://svnbook.red-bean.com/nightly/en/svn.reposadmin.html.

The Access Management feature enables you to edit data in the SVN access file online, in either repository scope or single project scope. It is an administration feature, so you must have administrator permissions for the scope you want to work with.

Accessing the Client

To use the Subversion Access Management client:

  1. Log in with administrator permissions for the repository or project you want to work with, and open it (see User Guide: Accessing Projects).

  2. If you are not in Administration after logging in, click the Administration link in the tool view of Navigation.

  3. In Navigation (topics view), expand User Management and select Access Management. The Access Management page loads in your browser.

Using the Access Management Client

The Access Management page has 2 panes, top and bottom. The top pane enables you to browse through the repository structure as it is defined in the access file, and review the current Role and User assignments for folders and files. Keep in mind that this pane is a viewport into the SVN access file... what you see is what is currently in that file.

The upper pane displays a string that shows the repository path to the currently selected folder or file. Some or all of the folder names in the path are clickable depending on your permissions:

  • If you have global (Repository) administrator permissions, the all folder names in the path are clickable enabling you to navigate all the way up to the repository root.

  • If you have project administrator permissions, the full path to the project folder is displayed, but you will not be able to navigate higher than the project root folder.

The lower pane of the Access Management page provides detailed information about access rights currently defined for the folder or file selected in the top pane. In the lower pane you can:

  • Add, edit, or remove Role assignments for the selected folder or file. Click the (Edit) icon in the Roles Assignment section in the lower pane of the Access Management page.

  • Add, edit, or remove User assignments for the selected folder or file. Click the (Edit) icon in the Users Assignment section in the lower pane of the Access Management page.

    Note the assigning access by Role is generally considered better practice than by User.

  • Review Users and Roles that currently have read and write permission for folder or file currently selected in the upper pane.

  • Review Users and Roles that currently have read-only permission for the folder or file currently selected in the upper pane.

By default, files in a folder have the same access permissions as the containing folder.

Editing Role Assignments

In either scope, you can edit Role assignments. This is generally considered preferable than assigning access to individual users.

To edit Role assignments:

  1. Open the repository or project you want to manage and navigate to User Management > Access Management in the Navigation pane.

  2. In the top pane of the Access Management page, browse to the repository folder or file for which you want to edit Role assignments and select the item. The selected folder or file's SVN access details appear in the lower pane.

  3. In the Roles Assignment section, click (Edit). The table of currently assigned Roles becomes editable. Each row of the table corresponds to a Role and the permissions currently assigned to it. The last row enabled you to specify a Role and its permissions to add to the currently selected folder or file. Columns correspond to user role and permissions. Check boxes correspond to enabling (checked state) and disabling (cleared state) each permission.

    TIP: Deny All overrides the other permission settings and revokes all permissions for the selected folder or file.

Adding Role Assignments

To add Role assignments:

  1. Make sure you are editing the correct folder or file - select it in the top pane of the Access Management page. If the Role Assignments table is not editable, click the (Edit) icon on the section header.

  2. In the last row of the table, click the icon to add a new row. Select the Role you want to add to the access file from the list in the Roles column. (For information about configuring Roles, see Administrator's Guide: Managing Users and Permissions: Configuring User Roles.)

  3. Check the boxes corresponding to the permissions you wish to assign to the added Role. The options are:

    • Read - check to assign read-only permission, clear to revoke it.

    • Read & Write - check to assign read and write permission, clear to revoke it.

    • Deny all - check to deny all permissions, clear to revoke denial.

  4. If you want to add another Role and set its permissions, click the icon in the Actions column to add another row to the table. Select the Role and assign permissions as described above.

  5. Click the Save button in the lower pane's toolbar to save changes from the GUI to the SVN access file.

Removing Role Assignments

To remove existing Role assignments:

  1. Make sure you are editing the correct folder or file - select it in the top pane of the Access Management page. If the Role Assignments table is not editable, click the (Edit) icon on the section header.

  2. On the row(s) of the Role(s) you wish to remove, click the in the Actions column. The row becomes highlighted. (If you make a mistake, click the Cancel button on the lower pane toolbar and start over.)

  3. Click the Save button in the lower pane's toolbar to save changes from the GUI to the SVN access file.

Editing User Assignments

As previously mentioned, it is generally considered preferable to assign Subversion access by Role rather than by User. The most common reason to edit User assignments is in situations where some "clean-up" of the access file is desirable, removing User assignments that may have found their way into the file at some time or another. Of course, if you wish to assign access to some specific User(s), you can do so.

To edit User assignments:

  1. Open the repository or project you want to manage and navigate to User Management > Access Management in the Navigation pane.

  2. In the upper pane of the Access Management page, browse to the repository folder or file for which you want to edit User assignments and select the folder. The selected folder's SVN access details appear in the lower pane.

  3. In the Users Assignment section, click (Edit). The table of currently assigned Users becomes editable. Each row of the table corresponds to a User and the permissions currently assigned. The last row enabled you to specify a user and permissions to add to the currently selected folder or file.

Removing User Assignments

To remove existing User assignments from the Subversion access file:

  1. Make sure you are editing the correct folder or file - select it in the upper pane of the Access Management page. If the User Assignments table is not editable, click the (Edit) icon on the section header.

  2. On the row(s) of the User(s) for whom you wish to remove SVN access, click the in the Actions column. The row becomes highlighted. (If you make a mistake, click the Cancel button on the lower pane toolbar and start over.)

  3. Click the Save button in the lower pane's toolbar to save your changes to the SVN access file.

Adding User Assignments

To add User assignments:

  1. Make sure you are editing the correct folder or file - select it in the upper pane of the Access Management page. If the Users Assignments table is not editable, click (Edit) icon on the section header.

  2. In the last row of the table, select the User to which you want to assign permissions from the list of in the Users column. (For information about configuring Users, see Administrator's Guide: Managing Users and Permissions: Configuring User Users.)

  3. Check the boxes corresponding to the permissions you wish to assign to the selected User. The options are:

    • Read - check to assign read-only permission, clear to revoke it.

    • Read & Write - check to assign read and write permission, clear to revoke it.

    • Deny all - check to deny all permissions, clear to revoke denial.

  4. If you want to add another User and permissions to the table, click the icon in the Actions column to add another row to the table. Select the User and assign permissions as described above.

  5. Click the Save button in the lower pane's toolbar to save changes from the GUI to the SVN access file.

The Tilde Exclusion Marker

Subversion access management enables use of the tilde character (~) as an exclusion marker. Prefixing a user name or role with this character causes Subversion to apply the access rule to users not matching the rule. Polarion displays access rules as they are written in the access file, so prefixed items may appear in the Polarion access management user interface if they exist in the access file.

The system property com.polarion.accessmngmt.useTildaFeatureForRoles in the polarion.properties file controls whether or not Polarion's Access Management should offer tilde-prefixed roles. The property is set to true by default.

You can find more information about this marker, along with some examples, in the Advanced Access Control Features section of the web page at http://svnbook.red-bean.com/nightly/en/svn.serverconfig.pathbasedauthz.html.

Access Control for Documents

Controlling access to Documents can be an issue in some organizations. While administrators cannot specify access control on specific Documents, it is possible to control access to Document folders. Document folders are found under the modules folder, under the project folder. If, for example, you wanted to set access control on the "User Requirements Specification" Document in Polarion's eLibrary example project, you would set the desired permissions on the folder elibrary/modules/Specification/User Requirements Specification.

When access management restricts a user from accessing a Document, the Polarion user interface does not show the Document to the user in Navigation.

Note for Global Administrators

If your user account has global (i.e. repository-scope) administrator permissions, but you are editing Role access in the project scope, then the appearance of some items in the Roles list is somewhat different than for administrators having just project-scope administrator permissions. Global administrators will see Roles prefixed with a project ID: myproject-project_developer or myproject-project_user, for example. A project administrator would see the same roles as project_developer and project_user.

Removing Unused Excel Import Configurations

If some Excel Import Configurations become disused or obsolete over time, they can be removed via the Repository browser. Import configuration may be save either in the global/repository scope or in the scope of some project. Deleting an Import Configuration does not require administrator permissions, but the user performing the removal must have permissions to delete content from the repository in the relevant scope.

The Repository Browser path to Excel Import Configurations is:


Configuring the Dashboard

Scope(s): repository, project

The Dashboard topic is implemented as a page in the integrated Wiki. You can customize the layout and content of this page using the macros discussed in this section. (Details on macro syntax are provided in the embedded Wiki Syntax Help in the Polarion portal).

Macros for Layout

You can organize the content of the dashboard into table and or column structures using these macros:

  • {table} - creates a table structure

  • {section} - defines a page section

  • {column} - divides a section into columns

  • {style} - enables embedding of CSS styling into the Dashboard (and other wiki pages)

Again, please refer to embedded syntax help for syntax and usage examples of these macros.

Macros for Information

There are several macros which roll up and display information from the system in the Dashboard. The most important ones are:

  • {fact}

  • {linechart}

  • {piechart}

  • {report}

Macro: {fact}

This macro renders some useful values from factbase. These values are stored for example in the workitems-data.xml file under the data folder of the Polarion installation. For example, the file for the repository level is located in: %POLARION_HOME%/data/RR/default/.reports/xml/workitems-data.xml.

This xml file contains computed values that can be rendered as numbers or graphs: UNRESOLVED-BY-ASSIGNEE, OPEN-BY-SEVERITY, STATUS and so on. Values are populated by reports (see Administrator's Guide: Configuring Reports.

Macros: {linechart}, {piechart}, {report}

The {piechart}, {piechart}, and {report} macros render information from HTML and XML files generated automatically by system calculations. The main thing you need to understand about them is that the path in their report-path is a relative path in the PR directory.

For example, if a macro is executed in project elibrary then the path is relative to the reports for that project.

Reference information about fact bases and values can be found in Administration Reference: Calculations and Facts.

Updating Dashboards

There is a calculation named all that calculates all metrics, charts etc. in a given scope. The default system configuration has a job named All Calculations that invokes this calculation. Schedule or call this job if you want to be sure that everything is freshly calculated.

Each section of the Dashboard contains an Update button which can be used to recalculate and refresh specific information displays in the Dashboard.

Depending on what you have configured to appear in the Dashboard, you may only need run some calculations, as opposed to all calculations as described above. You should configure the specific reports that run the calculations for the data you are displaying in the Dashboard. For information, see Administrator's Guide: Working with Report Configurations.

Customizing XML Export Templates

Work Items can be exported to XML (see User Guide: Exporting Work Items: Exporting to XML. Export is accomplished by means of XSL templates (XSLT). You can create your own XSL templates to transform exported Work Items to another XML document, a HTML document, a plain text file, or PDF or RTF. When creating your own XSLT, refer to the Polarion XML Export Schema in the Administration Reference.

You can access the templates via the Administration interface: Work Items > Export Templates.

You can also use the integrated Repository Browser to access export templates. Templates are located on repository path /.polarion/tracker/export_templates/. You must use this tool to access the XSL templates.

XSL Template Naming Convention

Each of the exporters has a unique set of templates. Which template is used for which exporter is determined by the name of the template:

  • Transformed XML Export: *-xml.xsl

  • HTML Export: *-html.xsl

  • Text Export: *-txt.xsl

  • RTF and PDF Export: *-fo.xsl

Where to Deploy XML Export Templates

Upload your custom XML export templates to the export templates folder in the repository: .polarion/tracker/export_templates.

Customizing Excel Export Templates

Excel export templates enable you to set up different export scenarios for users of the Excel round-trip features. Templates specify which Work Item field are exported for round-trip, and the default type for new Work Items created via Excel round trip.

Several export templates used for exporting Work Items to Microsoft Excel format are provided in the xlsx: Microsoft Excel section of the Export Templates topic of Administration (Administration >> Work Items > Export Templates > xlsx: Microsoft Excel. Repository folder is /.polarion/tracker/export_templates/excel). You will probably want to create you own Excel export templates derived from Polarion's default templates.

The following sections discuss the characteristics of an Excel export template, and describe several commonly needed customizations:

Default Excel Export Templates

Polarion provides 3 default Excel export templates:

  • Basic.xlsx - Template with some basic column-to-field mapping. A good starting point for many customizations.

  • Empty.xslx - Contains the required tables (describe later), but nothing else. No columns are defined in the template sheet, and there is no default column-to-field mapping. If used for round-trip export, the export dialog fields selection is pre-filled with all columns that are shown in the Table view of Work Items.

    This template is best used as the basis for new templates developed "from scratch".

  • TimeReport.xlsx - this template defines a work time report. It serves as a good example of how to define calculated columns in your custom Excel export templates.

Start by downloading the Excel export templates and checking to see how much is already implemented that you can use. The Empty.xlsx template is the most basic template with minimal data. The Basic.xlsx template has some typically used fields and columns pre-defined. The Time Report.xlsx template has some examples of calculated columns. Create a copy of one of these export templates to use for your customizations.

Export Template Structure

Work Items are exported to an Excel table (a named region of the worksheet) named WorkItems. Your template must contain this table, which should contain only a header and one normal row - the "template" row (see figure below). In Polarion's pre-defined export templates, this table is found in Sheet 1. Any column in this template sheet that has the a column label corresponding to a Polarion Work Item field ID is automatically mapped to the corresponding field. This includes custom fields. You can add columns as needed. If you need to have column names that do not correspond to field IDs, use the mapping table on the Polarion sheet.

The pre-defined Excel export templates from Polarion also contain the Polarion sheet. This sheet specifies some settings for the exporter and enables column to field mapping when template column names do not correspond to Polarion Work Item field names. Your custom template should contain this sheet with the 2 tables from Polarion's default templates.

The first table in the Polarion sheet is a table of property-value pairs that enable you to set default values for two properties:

  • New Work Item Type - specify the type for any new Work Items that may be specified by end users in exported round-trip workbooks based on the template, and created in Polarion during re-import.

  • New Comments Column - a regular expression value that matches headers of columns that should be imported as new Work Item comments.

The second table on the Polarion sheet is a column-to-field mapping table. Use this table to map any columns in the template table of Sheet 1 whose column names do not correspond to Polarion field names. Each row corresponds to a column in Sheet 1 that doesn't have a column name matching a field ID. (If there are rows in this table that duplicate the mapping on Sheet 1 you don't need to remove them. The mapping will not be duplicated.)

When adding a new column and field row to the mapping table, be sure to use the Insert context menu on a row in the mapping table. Do not add rows outside the table. Rows inside the table will be shaded.

If you should happen to specify a field that doesn't exist, it will not appear to uses in the Export Work Items dialog when they select the Excel export option.

The end result of your customized template, when uploaded to the portal, should be that all fields you have mapped in the template appear to users as the default fields in the Selected Columns list of the Export Work Items dialog. It's recommended that you save your templates with different filenames from the default templates. You can upload your finished templates on the Export Templates page (described earlier) of Administration, then test them by invoking Export in the Work Items table and selecting xlsx: Microsoft Excel in the Format field. If you need to modify your template to correct errors (or for any reason), you can do so and re-upload it using the Replace existing export template with this upload option.

Figure 18.1. Customizing Excel Export Template

Customizing Excel Export Template

Sheet column to Polarion Work Item field mapping in an Excel export template

Making a Column Read-only

To make an export template column read only:

  1. Open the sheet of the export template containing the WorkItems region (normally on Sheet1).

  2. In the first row after the header row (the "template" row referred to earlier), select the cell you want as read only.

  3. On the cell's context menu, choose Format Cells.

  4. Select the Protection page of the dialog and check Locked.

Adding a Column

To add another column to the Excel export template:

  • Open the sheet of the export template containing the WorkItems region (normally on Sheet1).

  • On first row after the header row (the "template" row referred to earlier), drag the lower right corner of the right-most cell until you see the outline for a new column. (Or use the content menu of the right-most cell to insert a column to the right).

  • Set the value of the new column's header to the name of a Polarion field to which you want the column mapped.

    Alternatively, set the header value to any unique value, and then on the Polarion sheet add a row to the mapping table.

Adding a Calculated Column


Download and open the Time Report.xlsx export template to see an example of calculated columns.

To create a new calculated column in an Excel export template:

  1. Create a new column as described in the previous section, but do not map it to any field. Rather, specify a unique value in the column header.

  2. Enter the desired formula in the template row cell of the new calculated column.

    Note that you cannot use relative cell references. Rather you should use table column references. For example:

    =[Time Spent]+[Remaining Est.]-[Initial Est.]

    Again, the calculated columns in the pre-defined Time Report.xlsx export template can provide a useful example of such references.

Specifying Column for Test Step Iteration Numbers

Excel export for offline Test Case execution supports export of Test Cases with multiple Iterations of Test Steps. By default, the export template is configured to append a label for each Iteration to the Title column in the exported workbook. It is possible to configure which field displays the Iteration number in the property Append Iteration Label to Field in the hidden Polarion sheet. The default is the "title" field.

Configuring OLE Object Support

It is possible to import Microsoft Word documents that contain OLE objects. Polarion can display OLE Object thumbnails during Word document import. However, some additional third-party image converter software must be installed and configured before you can import such Word documents. OLE Objects in documents must contain their thumbnails in .emf or .wmf file formats, and the image converter used must support their conversion into JPEG. OLE Objects themselves are not imported, only their thumbnails.

Installation of third-party image converter, and configuration of Polarion to support OLE objects are covered in the Polarion installation guide documents for Windows and Linux, bundled with the respective distributions and available on product download pages on the Polarion Software web site (www.polarion.com).

Customizing the Login Screen

You can customize the Polarion portal login screen to display a custom logo or other image in place of the Polarion logo. The image must be hosted online in a location accessible to your Polarion server via http. Images may be GIF, PNG, or JPEG format. Recommended width is 100 pixels. (Height is scaled automatically.)

In a clustered environment where Polarion is served over multiple servers (physical and/or virtual), if a custom image is specified on the server that is the entry point for the system, the image will be used as the icon for each server's entry point. In an environment utilizing a single server, the custom image appears beside the Polarion logo.

To add a custom logo or image to the login screen:

  1. Using a text editor, open the system properties file polarion.properties (follow link for location).

  2. Add the following line to the file:


    ...where [IMAGE_URL] is the URL of the logo or other image you want to display in the login screen.

  3. Save the file.

The Polarion server must be restarted before the image will appear in the login page.

Repository Browser mime Types

The Repository Browser uses the following information to detect if a file is binary or text: the svn:mime-type property, the container (Tomcat) mime-type settings, and configuration parameters BinaryMimeTypes and BinaryMimeTypes set in the web.xml (located in the web client plugin folder of the Polarion installation: polarion/plugins/org.polarion.svnwebclient_n.n.n/webapp/WEB-INF/ - where "n.n.n" are numbers specifying a Polarion release number: 3.5.0, for example).

If mime type is detected in SVN properties or container settings, it is then looked up in the BinaryMimeTypes and BinaryMimeTypes lists. If the mime type isn't set or isn't present in those lists, then an automatic algorithm, which analyzes the first 1000 bytes of the file and returns the best guess at the file type, is used.

This approach still cannot guarantee 100% accuracy of file type reporting and file handing in the Repository Browser. For example, one organization might want to have a file type .xyz treated as binary, while another wants the same file type interpreted as text. If you find that some file types are not reported and handled correctly in the Repository Browser, or if you have some file types that you want to make sure are always interpreted correctly, you can edit the above-mentioned web.xml, setting mime-type mappings and interpretations in the BinaryMimeTypes and BinaryMimeTypes lists.

Advanced System Tuning

There are some system properties that can be useful for experienced Polarion administrators. These are set in the file system properties file polarion.properties.

Property: attachments.indexingOfAttachmentContent.enabled

When not present in polarion.properties, or if added to the properties file and set to true, indexing of the content of attachments is enabled. When enabled, attachments to Documents, Wiki pages, Work Items and Test Runs are indexed. Attachment indexing is performed by a background job when the server is started. Users may not be able to search attachments for some time until the indexing job is completed.

Regardless of the setting, other attachment fields (author, title, fileName, updated and length) are not affected by this property and are always indexed (and therefore searchable by users).

Example: attachments.indexingOfAttachmentContent.enabled=true

The attachments index can be explicitly refreshed via the Index and Cache page in Administration.

For a list of supported attachment file types, see the User Reference topic Attachment File Types.

Property: attachments.maxSizeOfIndexedAttachmentInMB

If property attachments.indexingOfAttachmentContent.enabled is enabled, this property sets the maximum file size, in megabytes, that will be indexed for content, and therefore searchable for content by users. If an attachment is larger than the value specified in this property, only the attachment fields (author, title, fileName, updated and length) are indexed and searchable.

The value can be either an integer value (file sizes of 1 MB or more), or a float value. If no value is provided, or the property is left out of the properties file, a default value of 50 MB will be used if attachments.indexingOfAttachmentContent.enabled is enabled. The default limit of 50 MB has been found generally suitable for Polarion installations meeting the recommended system requirements

The setting applies to all attachments to any content that supports them: Wiki pages, Documents, Work Items, Test Runs, etc. The limit also applies to imported documents. If users encounter "Out of Memory" errors when uploading attachments or importing documents, check the limit in this configuration setting and either adjust the setting, or add more system memory and storage, as needed to meet the needs of your users. Examples:

  • attachments.maxSizeOfIndexedAttachmentInMB=2

  • attachments.maxSizeOfIndexedAttachmentInMB=0.5 (i.e. 512 KB)

  • attachments.maxSizeOfIndexedAttachmentInMB=5.5 (i.e. 5.5 MB)

Property: maxAttachmentSize

Controls the size of any attachment in Polarion. If the attached file is bigger than the configurable limit, the upload is stopped. Applies to Work Item attachments, Wiki attachments, Document attachments, Test Run attachments, imported Documents, and uploads of Project Templates. This limit is set in bytes.

Property: com.polarion.durationHoursPerDay

Specifies the number of hours per work day. Requires an integer value (default value is "8"). Other type values are silently ignored and the default substituted. The setting applies globally and cannot be overridden in the project or project group scopes. The specified value appears read-only in the Work Items: Planning page of Administration.

Property: com.polarion.enumerations.objectEnumerationsLimit

Sets a hard limit on the number of items that are loaded into enumerated lists of system objects such as Documents, Pages, Test Runs, users, etc. Excess items cannot be selected in the UI. Default value is 10 000. You can set a whole number (for example, 200 ), or -1 for unlimited.

Take for example a custom field in which users select a Document from a drop-down list of Documents (provided by an object enumeration). If the system contains hundreds or thousands of Documents, populating the select list can take too long. Setting a lower limit in this property can significantly improve performance.

See also: com.polarion.ui.maxRenderedItemsInCombo.

Property: polarion.reindex.from.revision

  • Which revision is taken as the first one to process when Polarion is started for the first time, or if its runtime data were cleared (e.g. due to reindex).

  • Possible values are FIRST and HEAD.

  • Default value: FIRST.

  • setting this to HEAD will speed up fresh start significantly, but the history of Work Items will not be available (only changes done after the start).

Property: polarion.startup.disable.artifacts.auto.recognition

  • Controls whether or not build artifacts auto-recognition during startup should be disabled (affects only projects where there are no configured build artifacts and auto-recognition is not disabled on the project level).

  • The auto-recognition can be initiated manually from Administration.

  • Default value: false.

  • Setting the value to true will result in significant speed-up of first start or reindex.

Property: polarion.startup.disable.artifacts.change.detection

  • Controls whether or not detection of build artifacts-related changes should be disabled during startup (does not affect first startup or reindex or projects created while the server was not running).

  • Default value: false.

  • Setting the value to true will result in significant speed-up of restart.

Property: com.polarion.ui.maxRenderedItemsInCombo

Universally controls the number of items loaded into combo box lists. Default value is 100. Decreasing the value can improve loading of lists, if performance is noticed to be slower than optimal, which may occur if there are many projects with many concurrent users. Users can filter for excess items by typing a string of characters in the combo box. For example, assuming an item "Zebra Stripe Pattern", user can filter by typing zebra.

See also: system property com.polarion.enumerations.objectEnumerationsLimit.

Property: useDecimalHoursDurationFormat

  • Controls whether or not the value for hours in time reporting fields (Initial Estimate, Time Spent, etc.) must be entered as a decimal value rather than the default fractional.

  • Default value: false.

  • When set to true, hour durations in all time reporting fields are displayed and entered as decimal hours only - 22.33 for example. The examples displayed by clicking on the "?" next to time input fields are changed when this feature is enabled, and the export option Convert Durations to decimal hours is not displayed in the export dialog.

    Storage in XML persistence and pre-2011 LiveDocs is still in the fractional format, only hours are not converted to days. So the value in the example above is actually stored as 22 1/3h. It is stored that way rather than 22 33/100h because of smart parsing of user-entered values to the fractional format, which recognizes the decimal representation of fractions (y/3, y/6 and y/12). So for example entering 0.08 or 0.083 is parsed as 1/12h. The smart parsing can be disabled by setting the system property dontUseSmartDecimalHoursDurationFormatParsing to true.

Property: wordImport.ignore.[CLASS]

Where [CLASS] the short name of an object class from the docx4j library

  • Default value: false

  • Controls whether or not unsupported content, of the type represented by the specified class, is reported with the Unsupported Content message (see screenshot) in the result Document after importing a document from Microsoft Word.

By default, unsupported content contained in the import source is not imported, and is replaced by the graphical message shown below in the result Document after the import process finishes. If you would rather that such content be silently ignored, you can add this property for each type of unsupported content you do not want reported in the import result Document.

Figure 18.2. Unsupported Object

Unsupported Object

Graphical message when an object in a source document cannot be imported to Polarion. Set this property to suppress it.

Example: wordImport.ignore.R.DayLong=true where R.DayLong is the short name of the class of the object from docx4j library.

In this case, content objects of the R.DayLong class will be ignored during import and no message will appear in the import result. To find the class name, look at the tool-tip on the Unsupported Content message in an import result where some unsupported content was present in the source document.

Note that OLE thumbnails are supported for imported Word documents when third-party image converter software is installed and configured. See the User Guide topic Documents with OLE Objects for more information.

Property: com.polarion.logoURL

Optionally specifies the URL of a remotely hosted logo or icon image to display in the Navigation panel in lieu of the Polarion Software logo. The hosted location must be accessible to the Polarion server. If this property is not specified, the Polarion Software logo is displayed.

If specified, the remote image should ideally be 60 W x 64 H (pixels) in GIF, PNG, or JPG format. Larger images should ideally have the same aspect ratio,and will automatically be resized and cropped if necessary to fit the display space allocated by Polarion in the Navigation panel.

This can especially useful for organizations running multiple Polarion servers. A different logo image can be configured for each server, enabling end users to tell at a glance which one they are connected to.



Property: com.polarion.ui.lock.timeout

Optionally specifies a lock timeout in minutes for the Diagram Editor. When a user begins editing a diagram, a lock us set and no other user can edit it until the diagram changes are saved, the user closes the Diagram Editor, or the lock timeout set in this property occurs.

If this property is not specified, the lock timeout defaults to 8 hours. The user who obtained the lock must save the diagram or close the Diagram Editor in order to remove the lock.

Example: com.polarion.ui.lock.timeout=30 (Sets lock timeout to 30 minutes.)

Property: com.polarion.ui.login.resetPasswordLinkURL

Holds the URL of a page on your system that you have provided for users to reset their password. You must also set the resetPasswordLinkLabel property (below).



See also: Enabling Users to Reset Password.

Property: com.polarion.ui.login.resetPasswordLinkLabel

Link text to display on the Polarion portal login page, leading to your password reset page. You must also set the resetPasswordLinkURL property (above).


com.polarion.ui.login.resetPasswordLinkLabel=Reset Password

See also: Enabling Users to Reset Password.

Subversion Access by System User

On Polarion installations with large amounts of content, there can be significant performance benefits from setting up alternate access to the Subversion repository for the system user, especially for system indexing/reindexing.

The system property repoSystem can be used to provide an alternative repository URL to be used for read-only access by the system user. If this property is not set, the system user uses the normal access URL as specified by the repo system property.

Either of 2 protocols can be used when specifying the URL value in the repoSystem property:

  • The file:// protocol can be used when the SVN repository resides on the server computer's local drive. This is the simplest alternative, as nothing other than the repoSystem property needs to be configured. See warning below.

  • The svn:// protocol is faster, but it requires start-up of the svnserve server (part of the Subversion installation). With this protocol, if the repository resides on the server's local drive then the following can be used: svnserve -d --listen-host In this case, the repository is readable by anyone from the server computer (also true for the file:// protocol).


Polarion does not currently support the file:// protocol with Subversion 1.9 repositories. (That version is bundled with Windows distributions, but installers create the repository using version 1.8 format.) If you manually update to version 1.9 before full support by Polarion is declared, use only the svn:// protocol.



If the repository referenced via svn:// protocol is remote, then it will most likely be necessary to set up authorization for svnserve. You can find information about this in the svnserve documentation published online at: http://svnbook.red-bean.com/en/1.8/svn.serverconfig.svnserve.html.

Installing svnserve as a Service

The svnserve server can be installed as a service on Windows and Linux Platforms.


Run the following from the Windows Command line:

sc create SvnServe2Polarion binpath= "\"C:\Polarion\bundled\svn\bin\svnserve.exe\" 
--service -r C:\Polarion\data\svn\repo -R --listen-host" 
displayname= "SvnServe2Polarion" depend= Tcpip start= auto

Note that the above is a single command line. Please concatenate the above into a single line, leaving a space between them.


On Linux, installation of a service is OS-specific. On all supported distros, running svnserve in threaded mode is not recommended. Each spawned process on Linux instantiates its own cache, so this should be reflected in caching configuration of svnserve. The total amount of memory occupied by svnserve may be high, because a process is spawned for each connection and there might be dozens of such connections with highly concurrent use of Polarion.

The command to run by the service is:

svnserve -d -R -r /opt/polarion/data/svn/repo --listen-host

The exact path given as value of the -r argument is the root folder, which may vary. It needs to be reflected in the value of the repoSystem property, which contains the path relative to this given root. EXAMPLES:

"-r /opt/polarion/data/svn/repo" => repoSystem=svn://localhost


A facility for installing the svnserve daemon as a service on CentOS is available online: http://geek.co.il/2011/11/28/setting-up-subversion-svnserve-daemon-on-centos.

The svnserve caching has proved to boost performance significantly. Also consider adding some memory to the server, as the cache is in-memory. For details, see http://svnbook.red-bean.com/en/1.8/svn.serverconfig.optimization.html.

Work Items Tree Rendering

In the Tree view of Work Items, some user queries can return a tree so large that the performance of the entire system is adversely affected. Before constructing a tree of Work Items, Polarion checks two system properties with default values designed to prevent this. However, administrators can review and optionally adjust these depending on their system's resources.

The system property com.polarion.ui.treeTable.softLimit sets a first check limit on the number of items returned by a query run by a user in the Tree view. The default value is 1000. If you want to change that limit, you need to add this line to the system properties file: com.polarion.ui.treeTable.softLimit =500. (Replace "500" with an integer specifying the limit... it can be smaller or larger than the default 1000 items, depending on your system's resources.)

The check is performed on the number of items returned by the query. If the count exceeds the limit, the user is presented a dialog informing that the tree is large and can take a long time to load, and asking permission to display only the top N nodes (where N is the limit set in the above property). These top items can be on any level of the tree. This is neither the final number of nodes, nor the final number of roots. Rather, it is the initial number of roots. When the tree is created some of these items might be removed and others might be added.

If the user rejects loading of the top N items, a second condition is checked in the system property com.polarion.ui.treeTable.hardLimit (default value 10000). If the total number of nodes returned does not exceed this limit, the tree is constructed from the full query result. Otherwise, the user is shown a message that the tree is too large to show and has been limited to N nodes, where N is the value set in this property. Again, the administrator can set a higher or lower limit by adding com.polarion.ui.treeTable.hardLimit to the polarion.properties file.

Fonts and Font Substitution

The fonts available in LiveDoc Documents and rich text edit fields, and font-substitution for import and round-trip operations is configurable in the system property com.polarion.ui.richText.fonts.

Font substitution works for:

  • Import from Microsoft Word and Microsoft Excel.

  • Round-trip for the above.

  • Text copied from sources outside Polarion (e.g. from a Word document) and pasted into a LiveDoc or rich text field.

Font substitution replaces certain fonts with fonts defined in Polarion. Any font not available in Polarion and for which there is no substitution set is replaced by Polarion's default font.

Available fonts are separated by semicolon, and font substitution is separated by colon. Consider the following example:

com.polarion.ui.richText.fonts=Arial, Helvetica; "Courier New", Courier, monospace, HanWangKanTan; Georgia, Garamond; "Times New Roman", Times

  • Arial, Courier New, Georgia and Times New Roman are set as available fonts.

  • Helvetica is substituted by Arial

  • Courier, monospace, and HanWangKanTan are substituted by Courier New, etc.

The defined fonts must be installed on client computers. Any missing fonts will be substituted by the default font, Arial This is hard-coded into Polarion and cannot be changed by administrators.

Preventing SQL Database Update Blocking

Sometimes users can execute reports that use long-running SQL database queries. If this is not managed, system updates by other users can be blocked. A special set of system properties enable administrators to set some boundaries, and to receive email notifications of potentially problematic queries being run by users.

Property: com.polarion.platform.monitoring.notifications.disabled

Must be set to false in order for any system monitoring notifications to be sent.

For information on several other properties related to system monitoring emails, see Low Resource Notifications.

Property: com.polarion.platform.sql.notifier.minAttempts

Minimum number of attempts to interrupt a long-running query. Default value is 10.

Property: com.polarion.platform.sql.notifier.minTotalTime

Minimum total seconds for all attempts together. Default value is 300 seconds.

Property: com.polarion.platform.sql.notifier.killAfterLimit

Boolean, default valut is true. Controls whether or not to kill a long-running query that exceeds the limits set in the above 2 properties. If set to true, long-running queries exceeding the configured limits will be killed, a notification will be sent to administrators, and an exception is thrown and logged.

IMPORTANT: If set to false, the query is processed in further attempts with no limits, and no additional emails are sent concerning the query. Users may be blocked from saving their updates until the query is completed.

Lucene Word Splitting

In Version 2014-SR1, Polarion updated the embedded Apache Lucene query engines. The way indexed text is split into words changed from the previous Lucene version. Polarion now provides a system properties to enable administrators to control how words are split during query operations.

Property: search.wordBoundaries

Defines how word boundaries are defined for the index. Two values are supported:

  • splitByPattern - the input is split to words using a regex pattern. This is the default.

  • standard - the word boundaries are defined according to Unicode standard. This value should always be used for Asian languages

Property: search.wordBoundaries.splitByPattern

Defines the pattern to be used when using "search.wordBoundaries=splitByPattern". It is used with: java.lang.String.split(String).

Default value: \A[^\d\p{IsAlphabetic}]*|[^\d\p{IsAlphabetic}]*[\s]+[^\d\p{IsAlphabetic}]*|[^\d\p{IsAlphabetic}]*\Z

The default value ensures that the text is split by white-space, and the leading and trailing sequences of non-alphanumeric characters are removed from the remaining character sequences. The rest are "words" for the index. For example: Hello! WI-1234 _help_. is split to words Hello, WI-1234, and help.

JVM Properties for Maven Calculation

When updating to a new Polarion version, your current settings in JVM properties for Maven calculations may result in an Out of Memory (OOM) error PermgenSpace. In this case, you will need to adjust JVM memory values in the system file calculation.properties (repository path: .polarion/reports/calculation.properties.