1. Getting Started

Administration Basics

This section introduces the basic concepts of Polarion administration and configuration.

Administration rights

To be able to access Polarion's administration interface you must have a user account with Administrator level access rights. Access rights are defined by the "Role" assigned to the user account. Administration rights can have one of 2 scopes:

  1. Global: administrations rights for the entire repository

  2. Project: administration rights for a specific Project

The Default Administration Account

Polarion is installed with one default user account with user name "System Administrator" which has Global administration rights. The default log-in credentials for this account are:

  • User ID: admin

  • Password: admin

NOTE: Changing the Default Administration Password

The procedure for changing the password for the default System Administrator account is detailed in the Installation Guide that comes in the Polarion distribution. Look for: "Changing the default System Administrator password". For information about passwords, see Administration Reference: Passwords.

The default System Administrator account provides access to all Polarion administration and configuration features for the Polarion system and all Projects in the Subversion repository, and access to the repository itself.

Defining Additional Administrators

The main System Administrator may find it useful or necessary to grant administrative access to other Polarion users. For example, if the main administrator is absent for some reason, someone else in the organization should be able to perform system administration functions with Polarion. Another example: the manager of each Project might be given administrative rights for the Project(s) he/she manages. This enables the manager to add user accounts and assign user roles for the Project, among other things.

To define an additional administrator, first create a user account if one does not already exist. You can specify the new user's role(s) for the global system and/or per Project in the process of creating the account. For an existing user, you need to edit the user's account and specify his/her role(s) for the global installation and/or per Project.

For information on creating user accounts and defining user roles, see Managing Users & Permissions.

The Administration Interface

There are two ways that you can perform administrative functions in Polarion:

Most administration and configuration tasks can be done using the graphical user interface. This is the preferred approach for new or less experienced Polarion administrators.

Administration Scopes

Administration and configuration operations are generally possible in 2 scopes:

  • Global: Changes and customizations affect the entire repository.

    To work in this scope, select Repository in the Open Project or Project Group dialog.

  • Project: Changes and customizations affect one project only.

    To work in this scope, select any existing project in the Open Project or Project Group dialog.


There is another level of configuration/customization that controls behaviors and functions of the Polarion platform and features: the system configuration, contained in the system properties file polarion.properties. This file resides on the server's file system (see System Properties File Location), and requires editing outside the Polarion portal. Many users never need to modify the system configuration. The most frequently needed system configuration tweaks are covered in the topic Advanced Administration: Advanced System Tuning.

  • Changes in the global configuration and are inherited by all new projects created after any change/customization. Changes in the global scope do not propagate to projects that already exist before the changes.

  • New projects inherit the global configuration. Project-scope copies of all the global configuration files are created in the project's repository location. Changes in the project scope overwrite the content in the configuration files inherited from the global configuration.

  • Changes and customizations to a project cannot be rolled up to the global scope, nor can they be propagated to other existing projects. However, a customized project can be exported as a project template from which new projects with identical properties, configuration settings and content can be instantiated.

  • Project-scope settings always take precedence over global-scope settings.

  • Within a project-scope configuration, settings specific to a Work Item type take precedence over generic settings applicable to all Work Item types.


Do not remove any project-scope configuration file in order to use the respective global configuration in the project. This will interfere with the system's ability to resolve inheritance and precedence. It can prevent users from performing workflow actions, and cause other problems.

Either restore the original revision of the project-scope file from the repository, or if the global configuration has changed since the original revision, copy the current global-scope file to the project's repository location, overwriting the project-scope file.

EXAMPLE: Suppose a Work Item type "Defect". When looking for configuration settings for this type:

  1. The system looks for configuration settings for the Defect type in the current project.

  2. If none is found, the system looks for configuration settings for all Work Item types in the project.

  3. If none is found, the system looks for configuration settings for the Defect type in the global configuration.

  4. If none is found, the system uses the settings for all Work Item types in the global configuration.

Figure 1.1. Precedence Diagram

Precedence Diagram

Example of configuration scope precedence

Graphical User Interface

Actually, all administration functions are accessible via the graphical user interface (GUI) of the Polarion portal. However, not all configurations can be performed using graphical controls in the portal. Where graphical controls are not provided, configuration are performed by editing the respective XML configuration file. Such editing can be done on line or off line.

XML Configuration Files

Some administrative functions are performed by editing a relevant XML configuration file stored in the repository. These configurations are generally less frequently customized by most Polarion users. Where some configuration requires editing a configuration file, you have 2 options:

  • Edit the XML file online using the basic text editor provided in the portal web UI.

  • Download a copy of the configuration file to your local system, edit it locally, then upload the modified file back to the Polarion portal. (Upload and download controls are provided in the portal UI for each configuration file).

Figure 1.2. Accessing XML configuration files

Accessing XML configuration files

Edit XML configuration files locally or online

Sometimes configuration or customization is possible both globally, and also for projects (or sometimes project groups). Initially, there will be no configuration file for the more granular scope. In this case, you can download the global configuration file, modify it for the scope in which it applies, and upload the modified file to the repository URL applicable for the scope, or, in some cases, to the same URL but with the file renamed in a way that Polarion recognizes as applying to the more granular scope. You will find help texts in the GUI screen where you access to the configuration file which indicate where you need to upload the modified file, and/or how the modified file must be named to apply in a narrower scope.

You can create some project-scope configurations online without having to download/upload the XML configuration file. Where this capability is available, a labeled control or link is provided creating a project-scope configuration. Refer to help for individual configurations for specifics.

Figure 1.3. Project configuration

Project configuration

Customizing global configuration for a project

Resolving Problems & Troubleshooting

The Polarion platform is designed to be very easy to administrate and configure. But it is a very robust system, and no system is ever perfect. If you experience any problems, we suggest you try to look into the log files first (see Administration Reference: Log Files).

If you see that some items are missing, or do not display correctly, you check the Index and Reindex section in this guide. The index repair and rebuild procedures described there can resolve many issues.

If you are still unable to resolve some problem, please contact Polarion technical support. It will expedite matters if you can provide the following:

  • a detailed description of the problem and symptoms observed

  • log files from the time the problem occurred, and also log files from any reindex operation if you may have run when attempting to fix a problem.


On Linux you can use $POLARION_HOME$/bin/polarion.init tar-log to gather all relevant log files.

Setup for Internet Explorer Users

It is required that Internet Explorer be configured to include the URL of your Polarion server in the Local Intranet security zone.

To configure Internet Explorer on client computers:

  1. Log on to the client computer with the permissions necessary to change Internet Options.

  2. Start Internet Explorer, and on the main menu choose Tools > Internet Options, then click the Security tab.

  3. Select Local intranet and click the Sites button.

  4. In the Local Intranet dialog, click Advanced button

  5. In the field Add this website to the zone, enter the URL of your Polarion server. For example:

    http://polarion.mydomain.com or https://polarion.mydomain.com

  6. Click the Add button to add your Polarion server URL to the list of sites, then close the Local Intranet dialog.

  7. Click OK in the dialog until you are back to the Internet Explorer main menu.


Compatibility View is not supported by Polarion systems. Be sure it is disabled, otherwise users will see an error message and will not be able to log in via Internet Explorer until Compatibility View is disabled.