This section contains various reference topics pertaining to Polarion administration and configuration. For procedural information, please refer to the Administrator's Guide.
This section contains reference information about the default Polarion folder structure after installation. Where there are differences between Windows and Unix, these are noted. The Polarion folder structure is quite flexible - it depends directly on the installation procedure and Polarion configuration. The structure described here is the structure created by the default installation procedure.
In documentation, $POLARION_HOME$ means the root folder of a Windows installation. The default path used by the Windows installer is C:\Polarion.
After installation on a Windows system, the Polarion folder ($POLARION_HOME$) contains the following subfolders which are unique to the Windows installation (i.e. are not created during the Linux installation process):
This folder contains third-party applications that Polarion requires in order to work, and which are installed automatically by the Windows installer. If you chose not to have the installer install some application and manually installed it somewhere else, then it doesn't appear in this folder. For example, if you took the Custom installation option and unchecked the options to install Subversion and j2re 1.4.2, but chose to install Apache, then only the folder with the Apache distribution will appear here. By default, the bundled folder contains the following folders with the appropriate distributions:
apache_2.0.59
j2re_1.4.2
svn_1.4.3
*.lnk-files (desktop shortcuts) for starting and stopping the Polarion server and Apache services.
The Polarion installation procedure places binary, executable, and configuration files under (/opt/polarion). Data is stored at /opt/polarion/data on Linux, and the location is user-configurable. The Linux installation contains no folders that are unique to it (i.e., not present in a Windows installation).
This section covers folders that are common to both Windows and Linux installations.
Parent folder: /var/lib/polarion (Linux) $POLARION_HOME$ (Windows)
This folder contains all data that Polarion operates with. By default the following folders are present:
bir (Build Information Repository)
The projects folder contains builds of all projects.
logs
Log files
portal-data
Internal Polarion portal data
rr (Reports repository)
This folder contains project reports and reports configuration files (as global as for projects).
shared-maven-repo
Maven 2 repository accessible through http://.../maven2 by default
svn
This is the Subversion repository for Polarion. The folder contains both required files (access and passwd) and the repository itself (in the folder repo by default).
workspace
Contains: logs, manifest-files for plugins and some configuration files. You can view and remove Polarion log files here.
Contains: Polarion system files including configuration and properties files, plugins, license-related files, and Help files. The following subfolders are present:
configuration
Polarion configuration files including the polarion.properties file.
features
Properties files needed by various Polarion features.
license
Optional storage for your Polarion license file. Contains definition file specifying which users can use which product edition (in cases where you have a license for multiple product editions).
plugins
Polarion system plugins that enable Polarion to function. There are many subfolders. Documentation does not cover each one individually, as there is really nothing there that you as a user or administrator need to deal with. It may be worth noting that Help files are stored in the folder com.polarion.xray.doc.user_<n> (where <n> is the current version number). This can be useful should any Help updates be issued between releases and you need to install them manually.
The system processes used by Polarion are polarion.exe and one or more instances of java.exe or javaw.exe. The exact number of processes depends on the number of currently running jobs. In addition the these processes, the Apache service, Apache.exe also runs, and usually runs two processes with the same program name (i.e., Apache.exe).
Cron-like specification of moments in time when a job should be started
Table A.1. cron expressions for jobs
| Field Name | Allowed Values | Allowed Special Characters |
|---|---|---|
Seconds | 0 - 59 | , - * / * |
Minutes | 0 - 59 | , - * / * |
Hours | 0 - 23 | , - * / * |
Day-of-month | 1 - 31 | , - * ? / L W C * |
Month | 1 - 12 or JAN - DEC | , - * / * |
Day-of-Week | 1 - 7 or SUN - SAT | , - * ? / L C # * |
Year (Optional) | empty, 1970 - 2099 | - * / |
Legend:
* = all values
? = no specific value
, = additional value specification
/ = increments specification
- = range specifier
The following table contains examples of cron expressions used in job scheduling.
Table A.2. Examples of cron Expressions
| Expression | Meaning |
|---|---|
0 0 12 * * ? | Fire at 12pm (noon) every day |
0 15 10 ? * * | Fire at 10:15 am every day |
0 15 10 * * ? | Fire at 10:15am every day |
0 15 10 * * ? * | Fire at 10:15am every day |
0 15 10 * * ? 2006 | Fire at 10:15am every day during the year 2006 |
0 * 14 * * ? | Fire every minute starting at 2 pm (14:00) and ending at 2:59 pm (14:49), every day |
0 0/5 14 * * ? | Fire every 5 minutes starting at 2 pm (14:00) and ending at 2:55 pm (14:55), every day |
0 0/5 14,18 * * ? | Fire every 5 minutes starting at 2 pm (14:00) and ending at 2:55 pm (14:55), AND fire every 5 minutes starting at 6 pm (18:00) and ending at 6:55 pm (18:55), every day |
0 0-5 14 * * ? | Fire every minute starting at 2 pm (14:00) and ending at 2:05 pm (14:05), every day |
0 10,44 14 ? 3 WED | Fire at 2:10 pm (14:10) and at 2:44 pm (14:44) every Wednesday in the month of March |
0 15 10 ? * MON-FRI | Fire at 10:15 am every Monday, Tuesday, Wednesday, Thursday and Friday |
0 15 10 15 * ? | Fire at 10:15 am on the 15th day of every month |
0 15 10 L * ? | Fire at 10:15am on the last day of every month |
0 15 10 ? * 6L | Fire at 10:15am on the last Friday of every month |
0 15 10 ? * 6L 2003-2006 | Fire at 10:15 am on every last Friday of every month during the years 2003, 2004, 2005 and 2006 |
0 15 10 ? * 6#3 | Fire at 10:1 5am on the third Friday of every month |
Enumerations are lists of options that can be used in various Work Item fields or in building a search query. This section provides some reference information and examples of configurations in the XML configuration files for various enumerations. For information on accessing the configuration files and configuring enumerations, see Administrator's Guide: Configuring Enumerations..
At the top of the working area you will find a table of existing enumeration configuration files. Enumeration name is a hyperlink to an XML file that contains enumeration definition.
The General option might be defined in XML file as shown in the example below:
<option id="high" name="High" description="" color="#dd0000" iconURL="images/xray/enums/priority_critical.gif" sortOrder="1" />
Where:
option identifier, making up id is entrusted to user
this value will be shown in the list and better be self-explanatory
will affect option position in the list
For example, the file priority-enum.xml describes the ranges for float priorities. The minValue attribute defines the value where the range starts. The default attribute defines the priority to be shown as default when the work item is created.
An example of the Priority entry is given below:
<option id="medium" name="Medium" description="" iconURL="images/polarion/enums/priority_medium.gif" sortOrder="3" default="true" minValue="10" />
The rest of the fields of enumeration are optional.
XML file name has to end with "-enum" suffix (e.g. risk-enum.xml)
Configuration file workitem-type-enum.xml defines the types of work items. By default the following work items exist in the system:
A task is a common issue that requires some processing.
A request for change of appearance of functionality (including but not limited to bugs).
Functional or behavioral requirement to be fulfilled.
For link roles enumerations (like hyperlink-role-enum.xml, workitem-link-role-enum.xml) the attribute oppositeName exists. Value of oppositeName attribute is interrelated to the value of name attribute and describes back relation from linked item to the current (for example, name=relates to and oppositeName=is related to).
The following Work Item link roles are used in the system by default:
A generic relation type, more concrete link should be used where possible.
An example of configuration tag is given below:
<option id="relates_to" name="relates to" oppositeName="is related to" description="A generic relation type, more concrete link should be used where possible" iconURL="" sortOrder="1"/>
The behavior of depends on is the following:
a work item can be closed only if all the items on which it depends on are closed
if a work item is re-opened all the work items depending on it are re-opened
An example of configuration tag is given below:
<option id="depends_on" name="depends on" oppositeName="is depended on by" iconURL="" sortOrder="2"/>
The work item is a duplicate of another work item.
An example of configuration tag is given below:
<option id="duplicates" name="duplicates" oppositeName="is duplicated by" iconURL="" sortOrder="3"/>
An example of configuration tag is given below:
<option id="contains" name="contains" oppositeName="is contained by" iconURL="" sortOrder="4"/>
An example of configuration tag is given below:
<option id="parent" name="has parent" oppositeName="is parent of" iconURL="" sortOrder="4"/>
The work items, linked with the follow up link should be processed in the linking sequence.
An example of configuration tag is given below:
<option id="follow_up" name="has follow-up" oppositeName="is follow-up of" iconURL="" sortOrder="5"/>
Enumeration actions are implemented as hyperlinks. If you want to perform an action to an enumeration you should click on the appropriate hyperlink (for example, click on remove if you want to remove the enumeration). If a Project is currently selected, only enumerations uploaded for that project can be removed. Enumerations that belong to Repository (Global configuration) can be removed when the Repository node is selected in the Projects portlet.
This topic documents the default Work Item fields. Most of the fields can be modified as needed in the Administration perspective. Content of combo boxes and list boxes can be changed, and additional fields can be added as Custom fields. For more information, see Administrator's Guide: Configuring Enumerations.
Table A.3. Default Work Item Fields
| Field Name | Description |
|---|---|
Title | Each Work Item receives a unique ID automatically so Title should contain a short description of the Work Item. The item can be described further in the Description field. |
Type | The Type of a Work Item is descriptive of its nature. For example: "Bug", "Task", "Change request". Depending on the Type of Work Item, some type-specific fields can be present or absent in the detail display. For more information, see Administrator's Guide: Configuring Custom Fields. Changing the type of a Work Item resets the Work Item's workflow to the default Status value which can affect the automated planning of the item. |
Priority | The Priority field indicates the relative importance and the order in which a Work Item should be processed. This field is used by programmers/engineers to prioritize their work. Work Item with the highest priority should be processed first. The default values for the Priority field are configured in enumerations. In the system, the value is actually a float number. In the configuration you can define names for certain numerical values. For example: When editing a Work Item, you can specify your own numeric value in the Priority field - just choose enter a float value in the field control. |
Severity | This Severity field describes the impact on the end user or customer of the issue that triggered creation of the Work Item. The default values are given below:
The values can be configured in the relevant enumeration configuration. See Administrator's Guide: Configuring Enumerations. |
Status | The Status field indicates the Work Item's process phase: "New", "Resolved", "Closed", etc. Status values can be configured in the relevant enumeration configuration. See Administrator's Guide: Configuring Enumerations. The status changes are driven by the workflow configuration (see Administrator's Guide: Configuring Workflow). The field's combo box has an option which automatically sets the correct value for the field and triggers the next workflow actions including notifications, if any. Changing the Work Item status resets the Work Item's workflow to the initial status. This affects the planning of the Work Item. |
Resolution | Indicates the final outcome of a Work Item. The default values are:
You can customize the values in the relevant enumerations configuration file. See Administrator's Guide: Configuring Enumerations. |
Resolved On | This is a date field which is updated automatically when a Work Item is resolved. The value is the date the item was resolved. |
Author | This field contains the name of the Work Item creator, derived form his/her user account. The value is filled in automatically by Polarion and cannot be changed by users or administrators. |
Assignee | This field defines the person responsible for a Work Item. The specified person will receive automatic notification(s) the assignment and any changes to the Work Item. A Work Item can be automatically assigned to a user specified in the autoassignment configuration by selecting the value For information about the autoassignment configuration, see Administrator's Guide: Configuring Autoassignment. |
Created Date | The date a Work Item was created. The non-editable date value of this field is automatically assigned by Polarion and appears in the footer of the Work Item detail view. |
Updated | The date when a Work Item was last changed. The non-editable date value is automatically assigned by Polarion and appears in the footer of the Work Item detail view. |
Time Point | Time Points are similar to milestones (versions) or development iterations. The list of Time Points can be customized to suit your situation. For information, see Administrator's Guide: Configuring Time Points. |
Categories | This field enables you to flexibly categorize Work Items according to subsystem, customer, or whatever criteria you need. Category values provide an additional parameter that can be used in search queries. You can assign one or multiple Category values to any Work Item. For information on configuring Categories, see Administrator's Guide: Configuring Categories. |
Initial Estimate | This field is used in Polarion's project and time planning and planning accuracy metrics features. Here users specify an estimate of the amount of time that will be needed to resolve and close the Work Item. Time unit is specified with shorthand these characters: d for day(s), and h for hour(s). Time duration is specified by an integer value, or the literal
|
Time Spent | This field is used in Polarion's project and time planning and planning accuracy metrics features. Here users specify the actual time spent to resolve the Work Item. Time unit is specified with shorthand these characters: d for day(s), and h for hour(s). Time duration is specified by an integer value, or the literal
|
Remaining Estimate | This field is used in Polarion's project and time planning and planning accuracy metrics features. Here users specify the time remaining before the Work Item will be resolved. When a value is initially specified in the Initial Estimate field, the value of this field is automatically synchronized with it. Later, as the item is in progress, the assignee can modify the value here to that the progress on the item is reflected in the reports, metrics, and audits. Time duration is specified by an integer value, or the literal
|
Custom Fields | This section shows any custom fields which were manually added via the Custom Fields configuration. For information, see Administrator's Guide: Configuring Custom Fields. You can use custom fields to track any kind of Work Item you may require in addition to the default fields. Custom fields can be used as a parameter for search queries. |
Comments | This multiple entry field stores free-form text comments. There can multiple comments added by different users during collaborations and exchange of information. |
The list of roles is stored in roles.xml file.
Please refer to the permissions.xml file for the concrete permissions granted to these roles. The following table is a high-level description of the general meaning of individual permissions.
Table A.4. Default Roles and Permissions
| Role Name | Description of permissions |
|---|---|
| user | Global read access (all Projects); can log in and manage own profile |
| admin | Global administrator; all system permissions granted |
| developer | Global read/write access (excluding administration) in all Projects; run and browse reports and builds. IMPORTANT: cannot be assigned Work Items. This requires assignment of role assignable. |
| assignable | Global permission to have Work Items assigned. |
| guest | Read-only access; cannot change own profile/password. |
| project_user | Within a project: read/write access to project Work Items; can run (refresh) some project reports. |
| project_admin | Within a project: read/write access to the administration and configuration of the project |
| project_developer | Within a project: read/write access (excluding administration); run and browse reports and builds, but cannot be assigned Work Items. This requires assignment of role project_assignable. |
| project_assignable | Project-level permission to have Work Items assigned. |
For information on configuring roles, see Administrator's Guide: Configuring User Roles.
The global security configuration is stored in the /.polarion/security/permissions.xml file. The default configuration file is extensively commented and contains examples of the most common configurations.
Remember that this configuration can be done for each project, so there is checking for the existence of a project-level premissions.xml. If the privilege is being checked in some project context, then the project premissions.xml file is queried first and then (if needed) the global permissions.xml.
A project-level permissions.xml file is stored in PROJECT_FOLDER/.polarion/security/.
A Project Template is a directory containing files and additional information required for the creation of a new project. Content of the template is used to populate a newly created project with files.
Project templates are located in /.polarion/projects/templates/ in the Repository. All subdirectories in this location are considered as individual project templates.
Each project template must contain a file named template.properties in its root. This file has a standard Java properties file format. The following properties are recognized:
Short template name
Longer template description
Names of parameters required for project creation. Separated by ; (semicolon). The parameter names might contain letters, - (dash), and _ (underscore). Names are case sensitive.
List of files/directories to exclude from copying to a new project's directory tree. (template.properties is excluded automatically). Names cannot start with a / (forward slash).
List of text files where the parameters will be substituted during project creation. Files are separated by ; (semicolon). Names cannot start with / (forward slash)
Human readable names of parameters defined in the parameters property
Example of template.properties content is given below:
name=Empty Project
description=Empty project with no configuration.
process=.polarion/polarion-project.xml
parameters=project-name
param.project-name.name=Project Name
Other files/directories in the template directory are copied to the new project directory during the creation process (except those listed in skip property). Files with the name in the form _something are renamed to something. Files listed in the process property are assumed to be text files. During the project creation process, all strings having the form %param-id% are replaced by the actual parameter value. For parameters defined in the parameters property, there is also a predefined parameter project-id, which contains the ID of newly created project.
This topic provides a reference for the field types supported in the Polarion custom fields configuration. You can assign any of these types to a custom field.
For information on defining custom fields, see Administrator's Guide: Configuring Custom Fields.
string (single line)
text (multiple lines)
integer
float
currency
time
date
date-time
duration
boolean
enumeration - format: enum:ENUM_ID. See also: Administrator's Guide: Configuring Enumerations.
Check out the custom field and enumeration configurations in the demo projects that ship with Polarion.
This topic gives the basic file format of the artifacts.xml file which is used for configuring building.
<?xml version="1.0" encoding="UTF-8"?>
<artifacts xmlns="http://polarion.com/schema/Builder/Artifacts"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://polarion.com/schema/Builder/Artifacts"
<!- default value is "false" (the other is "true") ->
auto-recognition="AUTO_RECOGNITION_FLAG">
<artifact>
<type>TYPE </type>
<!-- location may be omitted in which case it is the project's location -->
<location>BASE_LOCATION_RELATIVE_TO_PROJECT'S_REPOSITORY_LOCATION </location>
<!-- resources may be omitted in which case the whole base location is used as a resource -->
<resources>
<!-- default value of recurse is "true" (other value is "false") -->
<resource source="REPOSITORY_LOCATION_RELATIVE_TO_BASE_LOCATION" target="TARGET_LOCATION_IN_LOCAL_DEPLOYMENT_SPACE" recurse="WHETHER_TO_USE_FOLDER_CONTENTS_AS_A_RESOURCE"/>
... <resource> ...
</resources>
... additional type-specific elements ...
</artifact>
<artifact>
...
</artifact>
</artifacts>
You can automate Work Reports by creating a scheduled job to run them. This section documents the report parameters and provides an example configuration.
The job is configured in .polarion/jobs/schedule.xml (Repository perspective, select Repository ).
Scale: day, week, or month
Grouping: comma-separated list of available groupings:
project
projectGroup
category
user
workItem
type
periodStart, periodFinish - date specification in one of the following formats:
date:yyyy-MM-dd
timePoint:TIMEPOINT_ID
firstTimePoint
lastTimePoint
projectStart
projectFinish
<job name="Work Report" id="tracker.workreport" cronExpression="0 0 0 ? * *" scope="system">
<fileName>scheduled_work_report_{yyyy-MM-dd}.xls</fileName>
<overwrite>true</overwrite>
<title>Work Report</title>
<scale>week</scale>
<grouping>project,user</grouping>
<query></query>
<periodStart></periodStart>
<periodFinish></periodFinish>
<job>
fileName can be specified with date-time format. For example: work_report_{yyyy-MM-dd}.xls. The format can be any Java SimpleDateFormat. The actual file name will be created replacing the {FORMAT} part with the formatted current date.
If overwrite attribute is False, and a work report with the same file name already exists, the job will fail.
Only work records from work items matching the query and dated within the specified period are exported
If query is not specified, both periodFinish and periodStart must be specified
This section documents the conditions and functions available for configuring workflow. For procedural information, see Administrator's Guide Configuring Workflow.
Type: condition
Description: Traverses incoming and outgoing links of defined roles and passes if all target work items are in one of valid states.
Parameters:
back.link.roles: comma separated list of incoming link roles to check
link.roles: comma separated list of outgoing link roles to check
valid.states: comma separated list of valid states
Type: function
Description: Traverses incoming and outgoing links of defined roles, finds all target work items and checks if they are in one of valid states. Those work items, that are not in one of the valid states, are put to the target state and optionally some of their fields are cleared.
Parameters:
link.roles: comma separated list of outgoing link roles to check
valid.states: comma separated list of valid states
target.state: status to which found work items will be set
clear.attribs: attributes that should be cleared for found Work Items
Type: function
Description: Changes value of given field - only setting of date field to current date is supported.
Parameters:
field.name: name of the field to be changed
field.value.type: only "current.date" is supported; this means that the field is set to the date when the transition was performed.
Type: condition
Description: Checks that there is a linked or backlinked work item. Optionally, required link role and target work item type may be specified.
Parameters:
backlink: true or false (optional, default is false)
link.role: required role of the link (optional, e.g. "implements")
target.work.item.types: required target work item type (optional, e.g. "defect")
Type: condition
Description: Tests whether a field is empty or non-empty. Field is empty if it is missing, or if its value is null or it is an empty collection.
Parameters:
field.name - name of the field to check
negate - Possible values: "true" or "false". If true, the condition will be passed if the field is empty. If false (the default value), the condition will be passed if the field is non-empty
This section documents the various log files and their purpose.
log4j-TIMESTAMP.log - generic log file, contains everything
log4j-data-TIMESTAMP.log - messages related to data processing
log4j-errors-TIMESTAMP.log - errors only
log4j-jobs-TIMESTAMP.log - messages related to scheduled jobs
log4j-licensing-TIMESTAMP.log - messages related to license(s) and license usage
log4j-startup-TIMESTAMP.log - messages related to startup and reindex process
log4j-tx-TIMESTAMP.log - statistics data
Windows location: C:/Polarion/data/workspace/.metadata
Linux location: /opt/polarion/data/workspace/.metadata Note that the /opt/polarion/data location is configurable during installation and so what you find on your system may not correspond to the default. sated here.
Apache log files are found in the following locations:
Windows: C:\Polarion\data\logs\apache
Linux: /var/log/apache or /var/log/httpd
Available log files are (as defined in the bundled Apache configuration):
access.log or or access_log - all accesses to Apache (and thus also Polarion through web portal) and Subversion
error.log or error_log - Apache errors
mod_jk.log - messages related to communication between Apache and Polarion (mostly this will be a log of communication related errors)