1. Administration Reference

This chapter contains various reference topics pertaining to Polarion administration and configuration. For procedural information, please refer to the Administrator's Guide.

Reference Topics

Polarion Folder Structure

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.

Windows structure

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):

bundled

This folder contains several 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 option to install Subversion, but chose to install Apache and PostgreSQL, then only the folders with the Apache and PostgreSQL distributions will appear here. By default, the bundled folder contains the following folders with the appropriate distributions:

  • apache

  • postgres

  • svn

Note

Java is also required in order to run Polarion ALM. However, it is no longer bundled due to licensing issues. It is necessary to obtain and install the Java version recommended in the Polarion Installation Guide for Windows, a PDF document included in the Windows distribution.

polarion shortcuts

*.lnk-files (desktop shortcuts) for starting and stopping the Polarion server and Apache services.

Linux structure

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

Common folders

This section covers folders that are common to both Windows and Linux installations.

data

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 integrated Subversion repository. 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.

polarion

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 system configuration 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.

Passwords

In general, local users (i.e. users mentioned in passwd file) cannot have non-ASCII passwords (i.e. passwords containing characters not available in the US-ASCII character set. However:

  1. If Polarion server is running on Linux, LDAP users can have non-ACSII passwords provided the following line exists uncommented in the polarion.properties (follow link for location):

    svnkit.http.encoding=UTF-8

  2. If Polarion server is running on Windows, LDAP users can have passwords containing characters from a subset of non-ASCII characters if one of the following lines exists uncommented in the polarion.properties file:

    svnkit.http.encoding=iso-8859-1

    svnkit.http.encoding=<LOCAL_CHARSET>

    The first allows passwords containing characters from the ISO-8859-1 encoding. <LOCAL_CHARSET> in second should be replaced with a local Windows encoding (e.g. windows-1250). When one of the encodings is specified, then passwords containing characters from the specified encoding will work.

Note

The ASCII double-quote character (") may not be used in local passwords.

Polarion System Processes

The system processes used by Polarion are polarion.exe and one or more instances of java.exe or javaw.exe (on Linux, java). The exact number of processes depends on the number of currently running jobs. In addition to these processes, the Apache service, httpd.exe (on Linux, httpd) also runs, and usually runs two processes with the same program name (i.e., httpd.exe on Windows, or httpd on Linux).

System Properties File Location

The system properties file polarion.properties contains configuration settings affecting various system processes and functions. This file resides on the server's file system. The path varies according to the server operating system hosting the installation:

  • Windows: %POLARION_HOME%\polarion\configuration\polarion.properties

  • Linux: %POLARION_HOME%/etc/polarion.properties

NOTES:

  • The system properties file can be edited using a text editor application such as Notepad or Vi. (There is no user interface for it in the Polarion portal.)

  • It is highly recommended to make a backup copy of the current production version of the system properties file before modifying it. Then if the modified file causes problems, you can easily restore the last working version.

  • Changes to system properties do not take effect until the Polarion server is restarted.

Scheduler cron information and examples

Cron-like specification of moments in time when a job should be started

Table 1.1. cron expressions for jobs

Field NameAllowed ValuesAllowed 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 1.2. Examples of cron Expressions

ExpressionMeaning
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 * * ? 2006Fire 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 WEDFire at 2:10 pm (14:10) and at 2:44 pm (14:44) every Wednesday in the month of March
0 15 10 ? * MON-FRIFire 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 ? * 6LFire at 10:15am on the last Friday of every month
0 15 10 ? * 6L 2003-2006Fire at 10:15 am on every last Friday of every month during the years 2003, 2004, 2005 and 2006
0 15 10 ? * 6#3Fire at 10:1 5am on the third Friday of every month

History Indexing Job

The DB History Creator job indexes the embedded SQL database layer, updating it with the most current history data from the repository.

History Indexing's performance has been greatly enhanced and now runs automatically.

(It can still be suspended, or resumed from the Monitor.)

Administrators that would like to have the job run periodically, at a scheduled time, can remove the disabled="false" property from the Cron Scripts via the Scheduler.

Setting the History Indexing job to run periodically:

To start the job at 7pm (Monday to Friday):

<job name="Resume DB History Creator" id="polarion.jobs.db.history" disabled="false" cronExpression="0 0 19 ? * MON-FRI" scope="system"/>                        
                    

To stop the job at 8am (Monday to Friday):

<job name="Suspend DB History Creator" id="polarion.jobs.db.history.killer" cronExpression="0 0 8 ? * MON-FRI" scope="system"/>
                    

Permissions Management

This section provides reference information that can be useful when configuring user permissions and user roles.

Permissions Configuration

Note

The information below is provided for programmers who may need to check permissions in some custom extension or script. Administrators should use the User Management > Permissions Management topic of Administration to configure user permissions.

The global security configuration is stored in the /.polarion/security/permissions.xml file.

Permissions configuration can be done for each project, so there can also be a project-scope premissions.xml. The project-level permissions.xml file is stored in PROJECT_FOLDER/.polarion/security/.

When parsing permissions, Polarion checks the project scope first and then, if needed, the global scope.

Default User Roles and Permissions

User roles are roles that can be defined and assigned by administrators. You can access the list of user roles in Administration: User Management: Roles. In Repository administration, only the repository-scope roles are shown. In project administration, only project-scope roles are shown. In addition to user roles, there are "dynamic roles". These are built-in roles used for controlling permissions for various artifacts such as Work Items and Documents.

The following tables provide a high-level description of the default user permissions. Note that permissions can be customized in the User Management: Permissions Management topic of Repository or project administration.

Roles assigned in the Repository (global) scope apply to all projects. For example if a user is given the global user role, that user will have the role and all globally configured permissions of the role in every project.

Table 1.3. Repository Scope

Role NameDescription of permissions
adminRepository administrator. All permissions are granted.
user Repository user. Users with this role can log in and manage their own account properties. A user with only this role, without any project role(s), cannot access projects. Note that login permission is tied to the user role and will not work if assigned to other roles... watcher, for example.

Table 1.4. Project Scope

Role NameDescription of Permissions
project_admin User granted access to Administration for the project in which the role is assigned. User has full administrator permissions within the scope of the project. User cannot access Administration in other projects where this role is not assigned him/her. User cannot access Repository Administration unless granted the role admin in that scope. Note that a user assigned that permission does not need to have the project_admin role assigned in any project.
project_approver Project-scope permission to review project content, including approving/disapproving Work Items, commenting Work Items and Documents, and resolving own comments. Users assigned this role for a project appear in the pick list of users who can be added as an Approving User in the Approvals section of the project's Work Items (available in the Table view of Work Items).
project_assignable Project-scope permission to have Work Items assigned. Users with this role appear in the pick list of users in the Assignee field of Work Items. By default this role has broad permissions allowing users to create, read, and modify project content, including browsing and running reports and builds.
project_user User is granted limited access to the project. User can read all objects but not modify or create them. User can download builds and view reports, but cannot initiate builds or refresh reports. Note that login permission for projects is tied to the user role and will not work if assigned to other roles... project_watcher, for example.

For information on configuring roles, see Administrator's Guide: Configuring User Roles.

Dynamic Roles and Permissions

Dynamic roles are built into Polarion for the purpose of controlling permissions for various operations on Work Items and Documents. For example, there is a dynamic role author for both of these artifact types. It has a default set of permissions, and an administrator can grant or revoke various permissions to/from the role if the defaults are not what is needed. The Document or Work Item's author will generally have broader permissions, DELETE permission for example, than users who have other roles.

Dynamic roles are "dynamic" in the sense that they are dynamically assigned to users by the system. For example, the creator of a Document is automatically assigned the document_author role, and the author of a comment automatically gets the comment_author role.

Administrators can modify permissions for dynamic roles in Global or project scope, in Administration > User Management > Permissions Management, in the By Permission tab. Dynamic roles appear in the Applicable Roles section of each Permission. For example, the author role appears in the MODIFY permission of Work Items (i.e. the author can modify the Work Item), but not in the CREATE NEW permission (there is no author until a Work Item is created).

The following sections outline the dynamic roles and their default permissions.

Dynamic Roles for Documents

Table 1.5. Document Dynamic Roles

Dynamic RolePermissions

document_author

  • Documents - Permission to READ

  • Documents - Permission to MODIFY FIELDS

  • Documents - Permission to MODIFY CONTENT

  • Documents - Permission to MANAGE

  • Documents - Permission to DELETE

  • Documents - Permission to COMMENT

  • Documents - Permission RESOLVE COMMENT

comment_author

Documents - Permission to RESOLVE COMMENT

Dynamic Roles for Pages

Table 1.6. Page Dynamic Roles

Dynamic RolePermissions

Page-Author

  • Pages - Permission to READ

  • Pages - Permission to DELETE

  • Pages - Permission to MODIFY

Dynamic Roles for Work Items

Table 1.7. Work Item Dynamic Roles

Dynamic RolePermissions

author

  • Work Items - Permission to READ

  • Work Items - Permission to DELETE

  • Work Items - Permission to MODIFY

  • Work Items - Permission to COMMENT

  • Work Items - Permission to RESOLVE COMMENT

assignee

  • Work Items - Permission to READ

  • Work Items - Permission to DELETE

  • Work Items - Permission to MODIFY

comment_author

Work Items - Permission to RESOLVE COMMENT

Dynamic Roles for Work Item Fields

Table 1.8. Work Item Field Dynamic Roles

Dynamic RolePermissions

author

  • Field [FIELD NAME] - Permission to READ

  • Field [FIELD NAME] - Permission to MODIFY

assignee

  • Field [FIELD NAME] - Permission to READ

  • Field [FIELD NAME] - Permission to MODIFY

Other Dynamic Roles

Table 1.9. Other Dynamic Roles

Dynamic RolePermissions

lead

  • Projects - Permission to VIEW

self

  • Accounts - Permission to MODIFY OWN ACCOUNT (Global scope only)

  • Accounts - Permission to MODIFY OWN TIME-SPLIT ASSIGNMENTS (Global scope only)

Permission Processing Scheme

When Polarion processes user permissions, it observes the following rules:

  1. A user may have multiple roles assigned that can be applicable in a given context. Roles can be global, project, or dynamic (e.g. author of a Work Item). Permissions for all roles are evaluated together; no role has precedence over others.

  2. Project permission overrides global. For example, if the global configuration GRANTS the permission, but project configuration DENIES the same permission, the permission is denied in the project scope.

  3. Custom Set permission overrides the generic permission. For example, if a Custom Set for Documents configuration GRANTS the permission to MANAGE for the "inReview" status, but the generic configuration DENIES the permission to MANAGE, a user is only able to manage Documents that have the "inReview" status.

  4. If GRANT / DENY permissions are both assigned to a user on the same level, then GRANT takes precedence.

    An example use case would be something like this:

    1. A user is assigned both a project_user role and a project_assignable role on the global level.

    2. The project_assignable role gives them permission to edit (MODIFY) Work Items, but the project_user role does not. (See screeenshot below.)

    3. Then the GRANT permission of the project_assignable role would override the DENY permission of the project_user role, and they would be able to edit Work Items.

See Configuring User Permissions for more details.

TIP

To avoid any role conflicts and confusion, it's a good idea to create a wide variety of roles to minimize users with more than one.

Note

The Global admin role always has all permissions granted in all Projects, and this cannot be overridden, so you should be careful how widely you assign that role.

Fields With READ Permission

Administrators can configure the READ permission for Work Item fields in Administration: User Management > Permissions Management: Work Items > Fields. The following Work Item fields have the READ permission, enabling administrators to grant or deny read access to different user roles at the field level:

  • Assignee

  • Attachments

  • Author

  • Boolean custom fields

  • Categories

  • Currency custom fields

  • Date custom fields

  • Date Time custom fields

  • Description

  • Due Date

  • Duration custom fields

  • Enum custom fields

  • Enum Multi-value custom fields

  • Float custom fields

  • Hyperlinks

  • Initial Estimate

  • Integer custom fields

  • Linked Revisions

  • Planned End

  • Planned In

  • Planned Start

  • Planning Constraints

  • Priority

  • Remaining Estimate

  • Resolution

  • Resolved On

  • Rich Text custom fields

  • Severity

  • Status

  • String custom fields

  • Test Steps custom fields

  • Text custom fields

  • Time custom fields

  • Time Point

  • Time Spent

  • Work Records

The following fields do not have configurable READ permission, and are therefore always readable for all users:

  1. Created

  2. Linked Work Items

  3. Project

  4. Title

  5. Type

  6. Updated

Fields With MODIFY Permission

Administrators can configure the MODIFY permission for Work Item fields in Administration: User Management > Permissions Management: Work Items > Fields. The following Work Item fields have the MODIFY permission, enabling administrators to grant or deny write access to different user roles at the field level:

  • Assignee

  • Attachments

  • Boolean custom fields

  • Categories

  • Currency custom fields

  • Date custom fields

  • Date Time custom fields

  • Description

  • Due Date

  • Duration custom fields

  • Enum custom fields

  • Enum Multi-value custom fields

  • Float custom fields

  • Hyperlinks

  • Initial Estimate

  • Integer custom fields

  • Linked Revisions

  • Linked Work Items

  • Planning Constraints

  • Priority

  • Remaining Estimate

  • Resolution

  • Resolved On

  • Rich Text custom fields

  • Severity

  • Status

  • String custom fields

  • Test Steps custom fields

  • Text custom fields

  • Time custom fields

  • Time Point

  • Time Spent

  • Title

  • Type

  • Work Records

The following fields do not have configurable MODIFY permission, and are therefore not modifiable by users:

  1. Author

  2. Created

  3. Planned End

  4. Planned In

  5. Planned Start

  6. Updated

Impact on Round-trip Operations

When a user is denied permission to MODIFY any Work Item fields, there can be several impacts on Work Item round-trip operations.

In round-trip import:

  • If the user re-importing a round-trip document is denied MODIFY permission for fields that have been changed externally in the round-trip document, those changed fields are ignored by the importer and a message is displayed.

  • If the re-imported file contains new Work Items which have fields for which the re-importing user is denied MODIFY permission, the file is imported but the MODIFY-denied fields are ignored and a warning message is displayed.

  • If the re-imported file contains new Work Items which have required fields for which the re-importing user is denied MODIFY permission, the import operation fails and a message is displayed.

  • If a user exported items and had MODIFY field permissions at the time of export, and that permission is subsequently denied before re-import, the re-import is allowed, but the MODIFY-denied fields are not updated in the portal, and a message is displayed.

  • In all cases, the logs of the import job specify any fields that were not updated by the import operation.

In round-trip export:

  • If the exporting user is denied MODIFY permission for some fields, those fields are read-only in the exported file.

In round-trip import:

  • IMPORTANT: If import is performed as another user that has more MODIFY permissions than the user who performed the export ("admin", for example), then all data are replaced.

Default Enumeration Configuration Files

This section lists the default enumeration configuration files and the Work Item fields they provide list item values for. Keep in mind that project templates may have different default configuration files for template-specific Work Item types, fields, etc.

Repository Scope

Table 1.10. Work Item Fields and Enumeration Configuration Files

Work Item FieldConfiguration FilenameWork Item Type(s)
Hyperlinks: Role hyperlink-role-enum.xml All
Priority priority-enum.xml All
Resolution resolution-enum.xml All
Resolution requirement-resolution-enum.xml Requirement
Risk risk-enum.xml All
Severity severity-enum.xml All
Severity requirement-severity-enum.xml Requirement
Status status-enum.xml All
Status requirement-status-enum.xml Requirement
Link Role workitem-link-role-enum.xml All
Type (of Work Item) workitem-type-enum.xml All
Work Records: Type work-record-type-enum.xml All

Notification Events and Targets

The section provides reference information about events and targets for notifications which is useful when customizing notifications.

Notification Events

Events occur when things change in the system... a user updates a Work Item, or a build finishes, for example. Notifications are sent to users in response to events. The tables in this section list and describe key notification events. In the configuration files, notification events are defined between <notification-config></notification-config> tags, and notification targets are inside events. The following events (and appropriate values of the <event_name> tag) are defined:

Table 1.11. Work Item Related Events Table

EventDescriptionParameters
workitem-createdOccurs when a new Work Item is created.filter
workitem-deletedOccurs when a Work Item is deleted.filter
workitem-commentedOccurs when a comment is added to a Work Item.filter
workitem-comment-removedOccurs when a comment is removed from a Work Item.filter
workitem-assignedOccurs when the Work Item Assignee field changes from None to some other valuefilter
workitem-updated Occurs when some other (unrecognized) change is made to a Work Item. Also triggered when another Work Item gets a link to the one affected by this event. fields, exceptFields, filter
workitem-status-changed Occurs when a workflow action is executed on a Work Item.statusFrom, statusTo, filter
workitem-attachment-addedOccurs when an attachment is added to a Work Item.filter;
workitem-attachment-updatedOccurs when an existing Work Item attachment is updated (i.e. new version of same attachment file is uploaded).filter
workitem-attachment-removedOccurs when an existing attachment is removed from a Work Item.filter
workitem-linkedOccurs when a specified Work Item is added to, or removed from another Work Item's set of linked Work Items. Can be configured per link role.roles, filter
linked-workitem-updated Occurs when another Work Item, linked from the specified one, is updated. For example, WI-1 links WI-2. When WI-2 gets updated, this event is triggered, allowing the WI-1 assignee to be notified. Can be configured per link role. fields, exceptFields, roles, filter
backlinked-workitem-updated Occurs when another Work Item, which links to the specified Work Item, is updated. For example, WI-1 links WI-2. If WI-1 gets updated, then this event is triggered, allowing the W-2 assignee to be notified. Can be configured per link role. fields, exceptFields, roles, filter
workitem-watcher-added Occurs when a watcher is added to a Work Item. 
workitem-watcher-removedOccurs when a watcher is removed from a Work Item. 
workitem-vote-addedOccurs when a user adds a vote for a Work Item. 
workitem-vote-removedOccurs when a user removes a vote from a Work Item. 
workitem-approval-addedOccurs when a user is added to the Approvals section of a Work Item.status, filter
workitem-approval-changedOccurs when a user is changed in the Approvals section of a Work Item.statusFrom, statusTo, filter
workitem-approval-removedOccurs when a user is removed from the Approvals section of a Work Item.status, filter
workitem-workrecord-addedOccurs when a work record is added to a Work Item.filter
workitem-workrecord-removed Occurs when a work record is removed from the Work Item.filter
revision-linked Occurs when a repository revision is linked to the Work Item.filter

The filter parameter is a sub-string of a query, the first part of which is supplied by the system when the filter is applied during a relevant event. The system supplies id:"x" AND, where "x" is the value of a Work Item ID. Therefore, the expression you supply in the filter parameter can start with the NOT operator. If the filter expression uses the OR operator, then it must be surrounded by parentheses.

Examples:

  • filter="(type:task OR type:defect)" - in effect, amounts to: filter="id:[workitemid] AND (type:task OR type:defect)"

  • filter="NOT (type:task OR type:defect)" - in effect, amounts to: filter="id:[workitemid] AND NOT (type:task OR type:defect)"

Table 1.12. Document Related Events Table

EventDescription
document-commentedOccurs when a comment or comment reply is added in a Document.
document-comment-removedOccurs when an existing comment is removed from a Document.
document-createdOccurs when a Document is created.
document-deletedOccurs when a Document is deleted.
document-movedOccurs when a Document is moved or renamed.
document-status-changedOccurs when the Status field of a Document changes (assuming Document workflow is configured).
document-updatedOccurs when a Document is updated.

Table 1.13. Plan Related Events Table

EventDescription
plan-createdOccurs when a Plan is created.
plan-updatedOccurs when a Plan is updated.
plan-deletedOccurs when a Plan is deleted.
plan-status=changedOccurs when the value of a Plan's Status field value changes.
plan-workitem-addedOccurs when a Work Item is added to a Plan, after Plan has started.
plan-workitem-removedOccurs when a Work Item is removed from a Plan, after Plan has started.

Table 1.14. Test Run Related Events Table

EventDescription
testrun-status-changedOccurs when the status of a Test Run changes, or when a new Test Run is created.
testrun-deletedOccurs when a Test Run is deleted.
testrun-updatedOccurs when a Test Run is updated.
testrun-finishedOccurs when the a value (date) is set for the finishedOn field of a Test Run.

Table 1.15. User Related Events Table

EventDescription
user-createdOccurs when a new user is created.
user-updatedOccurs when an existing user is updated.
user-deletedOccurs when an existing user is deleted.

Table 1.16. Build Related Events Table

EventDescription
build-finishedOccurs when a project build has finished running.

Notification Targets

Table 1.17. Table of Notification Targets

TargetDescriptionEvent Type(s)Parameters
affected-approveeWhen approval field is changed then only affected approvee(s) (added, removed, changed state) will be notified. Work Item 
affected-user Account owner will be notified about changes. This target works only for events user-created, user-updated, and user-deleted. User 
all-commentersAll users who have commented a Work Item or a Document.Work Item, Document 
all-votersAll users who have voted for the Work Item.Work Item 
all-watchersAll users who have been set as watchers of the Work Item. Work Item 
awaited-approveesAll users whose approval is awaited for the Work Item.Work Item 
comment-thread-participantUsers who commented in a threaded comments discussion will be notified if someone replies to the comment in the appropriate thread.Work Item 
current-assigneeThe assignee of the item. If assignee is changed during the action, both the original and the new assignee will receive notification.Work Item 
current-authorThe author of the Work Item. Work Item 
current-userThe currently logged-in user (the one who has made the change).Work Item, Module, User 
global-roleUsers having the global role specified in the required role attribute will be notified. (Example: global-role role="administrator")Work Item, Module, User, Buildrole
new-assigneeWhen assignee field is changed then only new assignee(s) will be notified.Work Item 
old-assigneeWhen assignee field is changed then only the old assignee(s) will be notified.Work Item 
project-leadThe user defined in the project's properties as the leader of the project to which the event belongs.Work Item, Module, Build 
project-membersAll users who have any role in the project to which the event belongs.Work Item, Module, Build 
project-roleUsers having the project-scope role specified in the required role attribute will be notified (Example: project-role role="project_assignable")Work Item, Module, User, Buildrole
single-emailNotification will be sent to the specified e-mail address in the email attribute (Example: email="someone@somewhere.org")Work Item, Module, User, Buildemail
single-userNotification will be sent to the user specified in the user-id attribute (Example: user-id="polarion_user_id")Work Item, Module, User, Builduser-id

Notifications are prioritized so that only one notification is sent to each user about a change. For example, adding an attachment and a comment will result in just one attachment notification if email is the target of both. However the one notification will cover all changes.

Users falling into 2 or more categories will receive only one notification. For example, both assignee and current user. Please note that not all targets may be used for every event. For example, it makes no sense to use the assignee target for a build-finished event.

System Variables

The following system variable are available and can be referenced in configuration of custom notification email subject lines.

Table 1.18. General System Variables

VariableDescription
$EVENT_NAME$General event name
$EVENT_USER_ID$The ID of the user whose action triggered the event
$PROJECT$ The project name that appears in the Subject line of email notifications
$SERVER_PREFIX$The prefix set in global notification settings

Table 1.19. System Variables for Builds

VariableDescription
$BUILD_STATUS$Status of a build (e.g. failed, aborted, ok)
$BUILD_PROJECT_NAME$Name of the project for which build was started
$BUILD_ARTIFACT_LABEL$Human-readable build artifact label (short description)
$BUILD_STAMP$Build's time stamp
$BUILD_BY_NAME$Name of the user who started a build

Table 1.20. System Variables for User Notifications

VariableDescription
$USER_EVENT_NAME$Name of an event, e.g. "User Updated"
$USER_NAME$Name of the user who has been changed
$USER_BY_NAME$Name of the user who evoked the notification

Table 1.21. System Variables for Work Item Notifications

VariableDescription
$WI_EVENT_NAME$The name of the event triggering the notification, or new status if status has been changed
$WI_ID$The ID of the changed Work Item
$WI_TITLE$The new title of the changed Work Item
$WI_ASSIGNEES$ The new assignees of the changed Work Item.
$PROJECT$ Holds the project name that appears in the Subject line of email notifications.

Table 1.22. System Variables for Module Notifications

VariableDescription
$MODULE_EVENT_NAME$Name of the module event triggering the notification
$MODULE_NAME$Name of the module that has changed
$MODULE_BY_NAME$Name of the user who evoked the notification

Default Notification Priorities

The following table lists the default priorities for notifications.

Table 1.23. 

Event namePriority
workitem-commented 0
workitem-comment-removed 0
workitem-workrecord-added 0
workitem-workrecord-removed 0
workitem-deleted 100
workitem-attachment-added 100
workitem-attachment-updated 100
workitem-attachment-removed 100
workitem-updated 200
workitem-approval-added 300
workitem-approval-removed 300
workitem-approval-changed 300
workitem-assigned 400
workitem-status-changed 500
workitem-created 600
workitem-linked 100
linked-workitem-updated 0
backlinked-workitem-updated 0
workitem-vote-added 100
workitem-vote-removed 100
workitem-watcher-added 0
workitem-watcher-removed 0
revision-linked 0
build-finished 100
module-created 700
module-deleted 700
module-updated 700
user-created 0
user-updated 0
user-deleted 0

Project Template Properties

Project template properties can be specified for custom project templates you create.

If Custom Templates are Used:

To have Polarion replace the Work Item Prefix from template-provided Work Items, add the following lines to your template.properties file: trackerPrefixToReplace=PREFIX, where PREFIX is the Work Item prefix specified in the project template's development project. For example, if your development project's Work Item prefix is "MYTEMPL", then you should specify trackerPrefixToReplace=MYTEMPL in the properties file.

process=.polarion/tracker/fields/workitem-type-enum.xml

These lines are added automatically in templates that ship with Polarion.

For information on project templates and creating custom project templates, see Customizing Project Templates

Each project template may contain a file named template.properties in its root. Use of this file is not required, but is recommended. The file has a standard Java properties file format. The following properties are recognized:

name

Short template name

description

Longer template description

parameters

Names of parameters required for project creation. Separated by ; (semicolon). The parameter names might contain letters, - (dash), and _ (underscore). Names are case sensitive.

skip

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

process

List of text files where the parameters will be substituted during project creation. Files are separated by ; (semicolon). Names cannot start with / (forward slash)

param.PARAM_ID.name

Human readable names of parameters defined in the parameters property

Below is an example of content found in the template.properties file:

name=Abc Software Project

description=Standard software development project for ABC-Corp, Inc. Development Teams

process=.polarion/polarion-project.xml

process=.polarion/tracker/fields/workitem-type-enum.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 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.

PDF Export Header/Footer Properties

This section lists the properties which can be specified in the PDF Export configuration to embed data values in the header/footer of PDF documents created by exporting a Page (including Classic Wiki) or a Document. Properties may render some stored data value such as revision number or project name, or a calculated value such as total number of pages.

The following table lists the available properties. Note that the Code column contains the string that should be specified in the configuration file. For example, you should specify the property code $[projectName] in the configuration, as opposed to the property name "ProjectName".

Table 1.24. Properties for PDF Header/Footer

NameCodeDescription

Revision

$[revision]

The revision number of the exported Page or Document

DocumentName

$[documentName]

The name of the Page or Document. Non-ASCII characters are not supported (see DocumentTitle below).

DocumentName1

$[documentName1]

The name of the first of two compared Documents or Pages. Non-ASCII characters are not supported (see DocumentTitle below).

DocumentName2

$[documentName2]

The name of the second of two compared Documents or Pages. Non-ASCII characters are not supported (see DocumentTitle below).

DocumentTitle

$[documentTitle]

The title of the Page or Document. This property supports non-ASCII characters and should be used instead of DocumentName by users of non-ASCII charsets

DocumentTitle1

$[documentTitle1]

The title of the first of two compared Documents or Pages. (Supports non-ASCII characters - see DocumentTitle.)

DocumentTitle2

$[documentTitle2]

The title of the second of two compared Documents or Pages. (Supports non-ASCII characters - see DocumentTitle.)

PageNumber

$[page]

Number of the current page of the PDF document

TotalPages

$[total]

Total number of pages in the PDF document

PolarionProductName

$[productName]

Name of the Polarion product used to export the PDF document

PolarionVersion

$[productVersion]

Version of the Polarion product used to export the PDF document

ProjectId

$[projectId]

ID of the project from which the content was exported to PDF

ProjectName

$[projectName]

Name of the project from which the content was exported to PDF

Space

$[space]

System ID of the space from which the content was exported to PDF

SpaceTitle

$[spaceTitle]

Title of the space from which the content was exported to PDF

Created

$[created]

Date when content was created in Polarion

CreatedBy

$[createdBy]

User name of the user who created the content in Polarion

Updated

$[updated]

Date when the content was past updated in Polarion

UpdatedBy

$[updatedBy]

User name of the user who last updated the content in Polarion

Generated

$[generated]

Date when the PDF document was generated (i.e. exported)

GeneratedBy

$[generatedBy]

User name of the user who generated (i.e. exported) the content to PDF

revision1

$[revision1]

For use when exporting revision comparison of a Document to PDF. This renders the revision number of the older of 2 compared revisions.

revision2

$[revision2]

For use when exporting revision comparison of a Document to PDF. This renders the revision number of the newer of 2 compared revisions.

It is also possible to reference Velocity variables and page parameters in the header/footer configuration. See Administrator's Guide: Configuring Documents and Pages: Configuring PDF Export.

Custom Field Types

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.

List of Basic Types

  • String (single line)

  • Text (multiple lines)

  • Rich Text (multi-line rich text)

  • Integer

  • Float

  • Currency

  • Time

  • Date

  • Date time

  • Duration

  • Boolean

  • Enum: (An existing Enumeration must be selected. See Administrator's Guide: Configuring Enumerations.)

  • Test Steps (Renders a table of Test Steps in Work Items of the selected type.)

TIP

Check out the custom field and enumeration configurations in the demo projects included in product distributions.

Enumeration Types

The following enumeration types encapsulate data from the Polarion portal into lists, which can be specified as the value for Enum type custom fields.

  • ID - The type ID which can be referenced in scripts and API calls.

  • UI Name - The type Name that appears in the pick list for Enum type custom fields in the Custom Fields editor in Administration.

  • Data - Data encapsulated by the type. Parameters are referenced in parentheses in scripts or API calls, as shown, and in labeled text box widgets in the Custom Fields configuration user interface.

Table 1.25. Enumeration Types

IDUI NameData

@build

Build

When no query is specified, all builds visible in the current project

@build[QUERY]

Build

All builds found by the query (using Lucene syntax) specified in the Query text box (or the QUERY parameter)

@category

Category

All Categories configured for the current project

@document

Document

When no query is specified, all LiveDoc Documents visible in the current project

@document[QUERY]

Document

All LiveDoc Documents found by the query (using Lucene syntax) specified in the Query text box (or the QUERY parameter)

@documentWiki

Documents and Pages

When no query is specified, lists names of all LiveDoc Documents and Pages in the current project

@documentWiki[QUERY]

Documents and Pages

All LiveDoc Documents and all wiki pages found by the query (using Lucene syntax) specified in the Query text box (or the QUERY parameter)

@plan

Plan

All Plans in the project. Not user-sortable.

@plan[QUERY]

Plan

All Plans found by the query (using Lucene syntax) specified in the Query text box (or the QUERY parameter)

@project

Project

When Project Group is not specified, all active projects in the system

@project[PROJECT_GROUP]

Project

All projects in the project group specified in the Project Group text box (or the PROJECT_GROUP parameter)

@projectGroup

Project Group

When Project Group is not specified, all top-level project groups in the system

@projectGroup[PROJECT_GROUP]

Project Group

All sub-projects of the project group specified in the Project Group text box (or the PROJECT_GROUP parameter)

@role

Role

All user roles in the current project

@testRun

Test Run

When no query is specified, lists the names of all Test Runs in the current project

@testRun[QUERY]

Test Run

All Test Runs found by the query (using Lucene syntax) specified in the Query text box (or the QUERY parameter)

@timePoint

Time Point

When no query is specified, all time points visible in the current project

@timePoint[QUERY]

Time Point

All time points found by the query (using Lucene syntax) specified in the Query text box (or the QUERY parameter)

@user

User

When Role is not specified, all active users (i.e., those users assigned role of user).

@user[ROLE]

User

All users assigned the role specified in the Role text box (or ROLE parameter)

@wiki

Wiki Page

When no query is specified, lists the names of all wiki pages in the current project

@wiki[QUERY]

Wiki Page

All wiki pages found by the query (using Lucene syntax) specified in the Query text box (or the QUERY parameter)

Building configuration file format

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>
                

Work Report Job Configuration

You can automate Work Reports by configuring 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 (Access this using the Repository Browser.)

Job Parameters

  • 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

Configuration Example

<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

Workflow Conditions and Functions for Work Items

This section documents the conditions and functions available for configuring workflow for Work Items. For procedural information, see Administrator's Guide Configuring Work Item Workflow. It also describes system handling of missing or invalid conditions/functions in the configuration file. See also: Workflow Conditions and Functions for Documents.

Workflow Conditions (Work Items)

This section documents the available workflow conditions for Work Items.

ApprovalState

  • Description: Tests whether all Work Item approvals have a specific workflow status.

  • Parameters:

    • commonApprovalState - the status value to be tested for... 'approved' or 'waiting', for example.

      If omitted, the condition testes for the 'approved' status. That is, whether all approvals have the 'approved' workflow status.

AtLeastOneApprovedAndNooneDisapproved

  • Description: Tests that at least one user has logged approval of the Work Item AND no user has logged disapproval.

  • Parameters: NONE

FieldNonEmpty

  • Description: Tests whether a Work Item 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, or an empty text (including Rich Text), or false Boolean value.

  • Parameters:

    • field.name - the field ID of the Work Item 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

LinkedWorkItem

  • Description: Checks, that there is at least one linked (or backlinked) item (optionally with given link role and type).

  • Parameters:

    • link.role (optional): Required link role

    • backlink (optional): If true, then backlinks are checked.

    • target.work.item.type (optional): Required linked Work Item type

LinkedWorkItemsStatus

  • 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

LinkedWorkItemType

  • 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")

RoleCondition

  • Description: Allows the action only if the current user has at least one of the roles specified in the roles parameter.

  • Parameters:

    • roles - Comma separated list of role names.

ScriptCondition

  • Description: Evaluate whether or not a specific workflow action is available according to the return value of a custom script, which is the result of the last line of the script. If the script returns Boolean value false, then the workflow action will not be available. If it returns some text, then the workflow action will not be available and the returned text will be shown as the reason.

  • Parameters:

    • engine: The name of the scripting engine to use. Groovy (groovy) and JavaScript/ECMAScript (js) are supported.

    • script: The name of the script to run as condition. (Script file must be stored in the scripts folder of the installation's file system.)

Example: Given the existence of a Javascript script with line "Test".equals(workflowContext.workItem.title); ...

The workflow condition will be fulfilled if the title of the Work Item is "Test".

For Custom Scripts

Custom scripts must be placed in a “scripts” sub directory in the $POLARION_HOME directory.

(C:/Polarion on Windows systems and /opt/polarion/ on Linux based systems by default, but may vary.)

If no "scripts" directory exists, create one.

(Administrators of UNIX/Linux based systems will require “Owner”, “User” and “Group” privileges and be set up as a Polarion “System User”.)

Note for Developers

An instance of com.polarion.alm.tracker.workflow.ICallContext is available as variable workflowContext, and com.polarion.alm.tracker.workflow.IArguments is available as variable arguments in the script. Also, it is possible to configure more parameters of the condition than engine and script, which are then accessible through the arguments variable in the script.

Workflow Functions (Work Items)

This section documents the available workflow functions.

AddDefaultApprovals

  • Description: Adds default approvals for the Work Item (i.e., sets approval status to 'waiting' for a specified list of users)

  • Parameters:

    • approvals.users: comma separated list of user IDs comprising the default list of approvals that are added to the Work Item when executing a workflow action.

    • approvals.roles: comma separated list of role IDs comprising the default role(s) for approvals. All users with a specified role are added to the Work Item when executing a workflow action.

  • Required Permission: Work Items: Permission to MODIFY

    (Configured in Administration: User Management: Permissions Management. See Administrator's Guide topic Configuring User Permissions for more information).

ChangeField

  • Description: Changes value of specified field. Only setting of a date type field to current date, or a date-time type field to the current date-time is supported. The value type set depends on the type of the target field.

  • Parameters:

    • field.name: the field ID of the field to be changed

    • field.value.type: only "current.date" is supported. It sets either date or date-time value depending of the type of the target field in specified in field.name.

ClearField

  • Description:Clears existing value in the specified Work Item field.

  • Parameters:

    • field.name - field ID of the field to clear. Field should not be a required field or an error can result.

CreateLinkedWorkItem

  • Description: Creates a linked or backlinked Work Item using a specified type, link role, and a set of categories. The new Work Item is auto-assigned.

  • Parameters:

    • type (required): Type of the new Work Item to be created.

    • link.role (required): Role of the link between original and new Work Item.

    • backlink (optional): if specified, the new Work Item is backlinked, otherwise it is linked.

    • categories (See note below): comma separated list IDs of the Categories to be applied to the new Work Item.

      NOTE: Whether or not this parameter is required depends on the general workflow configuration, which may or may not be set to require that Categories be specified when a new Work Item is created. The parameter is optional in the default global configuration.

LinkedWorkItemsStatusChange

  • 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

    • back.link.roles: comma separated list of incoming 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

MarkWorkflowSignaturesAsObsolete

  • Description: Removes all of the Work Item signatures signed on the statuses that precede the one you've defined it for.

    Example: If defined for say Reopen, then all workflow signatures that Reviewed and Approved the item, are removed if the Work item is reopened.

    (The removed signatures are still tracked in the Work Item's History.)

  • Parameter: None

  • Usage: A workflow status was signed off on, but needs amendments that invalidate the signature(s).

ResetApprovalsState

  • Description: Resets all approvals for the current Work Item to the 'waiting' state.

  • Parameters: NONE

  • Required Permissions: 'APPROVE/DISAPPROVE as ANOTHER USER' or 'RESET APPROVALS'.

    (Configured in Administration: User Management: Permissions Management. See Administrator's Guide topic Configuring User Permissions for more information).

ScriptFunction
  • Description: Invoke a custom script to perform some action(s) in conjunction with a workflow transition.

  • Parameters:

    • engine: The name of the scripting engine to use. Groovy (groovy) and JavaScript/ECMAScript (js) are supported.

    • script: Name of the script run when the Work Item action is invoked. (Script file must be stored in the scripts folder of the installation's file system.)

For Custom Scripts

Custom scripts must be placed in a “scripts” sub directory in the $POLARION_HOME directory.

(C:/Polarion on Windows systems and /opt/polarion/ on Linux based systems by default, but may vary.)

If no "scripts" directory exists, create one.

(Administrators of UNIX/Linux based systems will require “Owner”, “User” and “Group” privileges and be set up as a Polarion “System User”.)

Note for Developers

An instance of com.polarion.alm.tracker.workflow.ICallContext is available as variable workflowContext, and com.polarion.alm.tracker.workflow.IArguments is available as variable arguments in the script. Also, it is possible to configure more parameters of the condition than engine and script, which are then accessible through the arguments variable in the script.

SetDate

  • Description: Sets the specified field to the current date OR date-time, depending on the type of the target field.

  • Parameters:

    • field.name - field ID of the field to write to. The field specified must be of a type which is compatible with a date type OR a date-time type value.

Handling of Workflow Errors

Sometimes a workflow extension may be removed resulting in a missing or invalid condition and/or function which in turn impede the execution of some workflow action or actions. (Such situation can occur when the XML configuration file is edited directly and uploaded to the repository, as some advanced administrators prefer over using the Workflow Designer in Administration.) If such problems are introduced into the configuration file, Polarion handles it in the following ways:

  • Errors resulting from missing workflow conditions or functions are written to the main Polarion log file.

  • A user working in Polarion administration who attempts to edit a workflow configuration containing missing conditions/functions receives a warning dialog containing information about the missing conditions and/or functions.

  • If a workflow function is missing, then the action for which it is configured will always be disabled and the transition will not be possible.

    If a workflow condition is missing, then the action for which it is configured will not be disabled, but any attempt to save a Work Item after invoking such action will fail and an error will be logged.

Workflow Conditions and Functions for Documents

This section lists the workflow conditions and functions available for configuring Document workflow. (For conditions conditions and functions for Work Item workflow, see Conditions and Functions for Work Items.

Workflow Conditions (Documents)

This section documents the available workflow conditions for Documents.

RoleCondition

  • Description: Allows the action only if the current user has at least one of the roles specified in the roles parameter.

  • Parameters:

    • roles - Comma separated list of role names.

ScriptCondition

Exactly the same as ScriptCondition for Work Items, except that it is configurable in Document workflow actions. See ScriptCondition for Work Items.

FieldNonEmpty

  • Description: Tests whether a Document 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, or an empty text (including Rich Text), or false Boolean value.

  • Parameters:

    • field.name - the field ID of the Document 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

ContainsNoMatchingWorkItems

  • Description: - if the Document contains any Work Items matching the query, then the workflow action cannot be executed

  • Parameters:

    • query - Lucene query for Work Items that, if matched, will prevent the workflow action from executing

Workflow Functions (Documents)

This section documents the available workflow functions for Documents.

AddDefaultSigners

  • Description: Adds users to the list of invited signers for the transition to the selected Document status. Sets the signature status to "invited" for these users.

  • Parameters:

    • signedBy.users: comma-separated list of one ore more user IDs. These concrete users are added as signers. Mandatory if signedBy.roles is not specified.

    • signedBy.roles: comma-separated list of one ore more user roles (e.g. "project_approver"). Users assigned any of the specified roles are added as signers. Mandatory if signedBy.users is not specified.

    • signer.role: string, optional. Any meaningful string describing the organizational role of users signing a Document. E.g. "Signed for Legal Department".

    • target.status.id: string, mandatory. ID of the target workflow status to which Document can transition after signature policy is satisfied. E.g. approved for the "Approved" status.

ChangeField

  • Description: Changes value of specified Document field. Only setting of a date type field to current date, or a date-time type field to the current date-time is supported. The value type set depends on the type of the target field.

  • Parameters:

    • field.name: field ID of the Document field to be changed

    • field.value.type: only "current.date" is supported. It sets either date or date-time value depending of the type of the target field in specified in field.name.

ClearField

  • Description:Clears existing value in the specified Document field.

  • Parameters:

    • field.name - field ID of the field to clear. Field should not be a required field or an error can result.

InvokeAction

  • Description: Workflow transition is executed on all Work Items contained in the (filtered) Document. If any Work Item workflow action cannot be executed for some reason, then Document workflow action fails and user is informed.

  • Parameters:

    • statusId: terminal status of the workflow transition to be executed on the Work Items

    • actionId: action of the workflow transition to be executed on the Work Items

    • query: query that additionally filters items contained in the Document

MarkWorkflowSignaturesAsObsolete

  • Description: moves all workflow signatures in the specified states to state Obsolete, marks all verdict comments linked to the signatures as Resolved.

  • Parameter: signatureStates - default value is "Done", but can be a comma-separated list if you do not want to mark some contexts (such as "Open") as obsolete.

  • Usage: On a workflow action to reset/restart the review/signature process. For example:

    • Document must be reworked, current signatures should not apply to new version.

Note

Before invoking this function, users should have manually processed all signature comments for already Done states, so there should be no unresolved comments for a transition for which signatures are being marked as obsolete.

ResetSignaturesVerdict

  • Description: Resets all signatures to "invited" status. An example usage would be when invited signers have declined to sign, requiring modification of a Document and start of a new round of reviews and signatures.

  • Parameters:

    • signatureStates - default value is "Done", but can be a comma-separated list if you do not want to mark some workflow signature states (such as "Open") as obsolete.

    • target.status.id: string, optional. The ID of the target Status for the workflow transition. If not defined, then all signatures for unfinished workflow signatures will be reset, otherwise only signatures for specified status will be reset. The function accepts only single value as a parameter (a list of multiple parameters is not accepted).

  • Usage: On a workflow action starts another round of the review/signature process after signature was declined and Document had to be reworked. For example:

    • Document must be reworked because a signature for Mark as Approved action was declined, so signatures for that action need to be reset.

ScriptFunction

Exactly the same as ScriptFunction for Work Items, except that it is configurable in Document workflow actions. See ScriptFunction for Work Items.

SetDate

  • Description: Sets the specified Document field to the current date OR date-time, depending on the type of the target field.

  • Parameters:

    • field.name - field ID of the field to write to. The field specified must be of a type which is compatible with a date type OR a date-time type value.

Workflow Conditions and Functions for Test Runs

This section documents the conditions and functions available for configuring workflow for Test Runs. For procedural information, see Administrator's Guide: Configuring Test run Workflow. See also: Configuring Document Workflow and Configuring Work Item Workflow.

Workflow Conditions (Test Runs)

This section documents the available workflow conditions for Test Runs.

RoleCondition
  • Description: Allows the action only if the current user has at least one of the roles specified in the roles parameter.

  • Parameter: roles - Comma separated list of role names.

ScriptCondition

Exactly the same as ScriptCondition for Work Items, except that it is configurable in Test Run workflow actions. See ScriptCondition for Work Items.

FieldNonEmpty
  • Description: Tests whether a Test Run 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, or an empty text (including Rich Text), or false Boolean value.

  • Parameters:

    • field.name - the field ID of the Test Run 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

Workflow Functions (Test Runs)

This section documents the available workflow functions for Test Runs.

MarkWorkflowSignaturesAsObsolete
  • Description: moves all existing workflow signatures related to the Test Run to Obsolete state.

  • Parameters: none

  • Usage: Some workflow action that was signed needs to be done again. For example, a Test Run was executed and signed, but something has occurred resulting in a decision to execute it again.

SetDate
  • Description: Sets the specified field to the current date OR date-time, depending on the type of the target field.

  • Parameter: field.name - field ID of the field to write to. The field specified must be of a type that is compatible with a date type OR a date-time type value.

ScriptFunction

Exactly the same as ScriptFunction for Work Items, except that it is configurable in Test Run workflow actions. See ScriptFunction for Work Items.

Polarion Log Files

This section documents the various log files, where to find them, and their purpose. It also provides information about cleaning up of old log files to conserve disk storage.

Location of Log Files

The default location for log files is as follows:

  • Linux: /opt/polarion/data/logs/main

  • Windows: C:/Polarion/data/logs/main

Important

The default location is configurable. If you don't find log files at the location above, search your system for one of the log files named in the following section.

Log Files and Usage

  • log4j-TIMESTAMP.log - generic log file, contains everything. Important for technical support purposes.

  • 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-monitoring-TIMESTAMP.log - messages related to system monitoring, audit and repair

  • log4j-startup-TIMESTAMP.log - messages related to startup and reindex process

  • log4j-rpc-TIMESTAMP.csv - Information about RPC calls (GWT)

  • log4j-tx-TIMESTAMP.log - statistics data

Polarion (Log4j) Log Files

Apache log4j is used for logging. Its configuration file is polarion/plugins/org.apache.log4j_*/log4j.properties. It can be customized if copied to polarion/configuration/log4j.properties. A server restart is required for the configuration modifications to take effect.

Additional Log Files

The following additional log files are configurable on both Windows and Linux platforms:

  • logs/apache - Apache logs

  • logs/derby - Derby logs

Windows location: C:/Polarion/data,

Linux location: (The location varies depending on the Linux distribution installed.)

PostgreSQL Log Files

Log files for the PostgreSQL database are located on path C:/Polarion/data/logs/postgresql. These logs are rotated after 7 days.

Installation Log Files

Installation log files store information about the installation process. If you should experience problems with installation you can provide these files to Polarion Technical Support. Windows location: C:/Polarion/data/logs/install/*.log, Linux location: /var/log/polarion/*.log - the location is configurable on both platforms.

Log File Rotation

Polarion log files are rotated on weekly basis.

Apache log files are rotated as follows:

Removing Old Log Files

You can periodically remove old log files to optimize disk storage space on the server. For information, please see Administrator's Guide: System Maintenance: Recovering Disk Space: Cleanup of Old Log Files

XML Export Schema

The following is the XML schema for Polarion's XML Export feature. This is the schema of files that all the *.xsl templates transform (and also the schema of exported files that are created by the XML export option xml: XML Export if the Copy-xml.xsl template is used). You will need refer to this schema for any custom XSL templates you may create to use with XML Export.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xhtml="http://www.w3.org/1999/xhtml" targetNamespace="http://polarion.com/xml-export"
  xmlns="http://polarion.com/xml-export" elementFormDefault="qualified"
  attributeFormDefault="unqualified">
 
  <xs:import namespace="http://www.w3.org/1999/xhtml"
    schemaLocation="http://www.w3.org/2002/08/xhtml/xhtml1-transitional.xsd" />
 
  <xs:complexType name="Option">
    <xs:sequence>
      <xs:element name="property" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:simpleContent>
            <xs:extension base="xs:string">
              <xs:attribute name="id" type="xs:string" />
            </xs:extension>
          </xs:simpleContent>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="id" type="xs:string" />
    <xs:attribute name="name" type="xs:string" use="optional" />
    <xs:attribute name="isDefault" type="xs:boolean" use="optional" />
    <xs:attribute name="sequenceNumber" type="xs:integer"
      use="optional" />
  </xs:complexType>
 
  <xs:complexType name="User">
    <xs:sequence>
      <xs:element name="description" type="Text"
        minOccurs="0" />
      <xs:element name="email" type="xs:string" minOccurs="0" />
      <xs:element name="id" type="xs:string" />
      <xs:element name="name" type="xs:string" minOccurs="0" />
      <xs:element name="votes" type="WorkItemRefList" />
      <xs:element name="watches" type="WorkItemRefList" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="Approval">
    <xs:sequence>
      <xs:element name="status" type="Option" />
      <xs:element name="user" type="User" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="ApprovalList">
    <xs:sequence>
      <xs:element name="approval" type="Approval" minOccurs="0"
        maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="UserList">
    <xs:sequence>
      <xs:element name="user" type="User" minOccurs="0"
        maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="WorkItemRef">
    <xs:attribute name="workItemId" type="xs:string" />
    <xs:attribute name="projectId" type="xs:string" />
  </xs:complexType>
 
  <xs:complexType name="WorkItemRefList">
    <xs:sequence>
      <xs:element name="workItem" type="WorkItemRef"
        minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="Attachment">
    <xs:sequence>
      <xs:element name="author" type="User" minOccurs="0" />
      <xs:element name="fileName" type="xs:string" />
      <xs:element name="length" type="xs:positiveInteger" />
      <xs:element name="title" type="xs:string" minOccurs="0" />
      <xs:element name="updated" type="xs:dateTime" />
      <xs:element name="url" type="xs:anyURI" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="AttachmentList">
    <xs:sequence>
      <xs:element name="attachment" type="Attachment"
        minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="OptionList">
    <xs:sequence>
      <xs:element name="option" type="Option" minOccurs="0"
        maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
 
 
  <xs:complexType name="StringList">
    <xs:sequence>
      <xs:element name="item" type="xs:string" minOccurs="0"
        maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="Category">
    <xs:sequence>
      <xs:element name="description" type="Text"
        minOccurs="0" />
      <xs:element name="id" type="xs:string" />
      <xs:element name="name" type="xs:string" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="CategoryList">
    <xs:sequence>
      <xs:element name="category" type="Category" minOccurs="0"
        maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="Comment">
    <xs:sequence>
      <xs:element name="author" type="User" minOccurs="0" />
      <xs:element name="created" type="xs:dateTime" />
      <xs:element name="parentComment" type="xs:positiveInteger"
        minOccurs="0" />
      <xs:element name="text" type="Text" />
      <xs:element name="title" type="xs:string" minOccurs="0" />
      <xs:element name="visibleTo" type="StringList" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="CommentList">
    <xs:sequence>
      <xs:element name="comment" type="Comment" minOccurs="0"
        maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="Text">
    <xs:choice>
      <xs:element name="html" type="xhtml:Flow"/>
      <xs:element name="plain" type="xs:string"/>
    </xs:choice>
  </xs:complexType>
 
  <xs:complexType name="Hyperlink">
    <xs:sequence>
      <xs:element name="role" type="Option" minOccurs="0"
        maxOccurs="unbounded" />
      <xs:element name="uri" type="xs:string" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="HyperlinkList">
    <xs:sequence>
      <xs:element name="hyperlink" type="Hyperlink"
        minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="PlanningConstraint">
    <xs:sequence>
      <xs:element name="constraint" type="Option" />
      <xs:element name="date" type="xs:dateTime" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="PlanningConstraintList">
    <xs:sequence>
      <xs:element name="planningConstraint" type="PlanningConstraint"
        minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="Project">
    <xs:sequence>
      <xs:element name="active" type="xs:boolean" />
      <xs:element name="description" type="Text"
        minOccurs="0" />
      <xs:element name="finish" type="xs:date" minOccurs="0" />
      <xs:element name="id" type="xs:string" />
      <xs:element name="lead" type="User" minOccurs="0" />
      <xs:element name="location" type="xs:string" />
      <xs:element name="name" type="xs:string" />
      <xs:element name="start" type="xs:date" minOccurs="0" />
      <xs:element name="trackerPrefix" type="xs:string" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="TimePoint">
    <xs:sequence>
      <xs:element name="closed" type="xs:boolean" minOccurs="0" />
      <xs:element name="description" type="Text"
        minOccurs="0" />
      <xs:element name="earliestPlannedStart" type="xs:date"
        minOccurs="0" />
      <xs:element name="id" type="xs:string" />
      <xs:element name="name" type="xs:string" minOccurs="0" />
      <xs:element name="time" type="xs:date" />
 
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="WorkRecordList">
    <xs:sequence>
      <xs:element name="workRecord" type="WorkRecord"
        minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="WorkRecord">
    <xs:sequence>
      <xs:element name="comment" type="xs:string" minOccurs="0" />
      <xs:element name="date" type="xs:date" />
      <xs:element name="timeSpent" type="xs:string" />
      <xs:element name="user" type="User" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="LinkedRevisionList">
    <xs:sequence>
      <xs:element name="linkedRevision" type="LinkedRevision"
        minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="LinkedRevision">
    <xs:sequence>
      <xs:element name="message" type="xs:string" minOccurs="0" />
      <xs:element name="revision" type="xs:string" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="RevisionList">
    <xs:sequence>
      <xs:element name="revision" type="Revision" minOccurs="0"
        maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="Revision">
    <xs:sequence>
      <xs:element name="author" type="xs:string" />
      <xs:element name="created" type="xs:dateTime" />
      <xs:element name="internalCommit" type="xs:boolean" />
      <xs:element name="message" type="xs:string" />
      <xs:element name="name" type="xs:string" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="LinkedWorkItemList">
    <xs:sequence>
      <xs:element name="linkedWorkItem" type="LinkedWorkItem"
        minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="LinkedWorkItem">
    <xs:sequence>
      <xs:element name="revision" type="xs:string" minOccurs="0" />
      <xs:element name="role" type="Option" />
      <xs:element name="suspect" type="xs:boolean" />
      <xs:element name="workItem" type="WorkItemRef" />
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="WorkItem">
    <xs:sequence>
      <xs:element name="fields">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="approvals" type="ApprovalList"
              minOccurs="0" />
            <xs:element name="assignee" type="UserList"
              minOccurs="0" />
            <xs:element name="attachments" type="AttachmentList"
              minOccurs="0" />
            <xs:element name="author" type="User" minOccurs="0" />         
            <xs:element name="categories" type="CategoryList"
              minOccurs="0" />
            <xs:element name="comments" type="CommentList"
              minOccurs="0" />
            <xs:element name="created" type="xs:dateTime"
              minOccurs="0" />
            <xs:element name="description" type="Text"
              minOccurs="0" />
            <xs:element name="dueDate" type="xs:date"
              minOccurs="0" />
            <xs:element name="hyperlinks" type="HyperlinkList"
              minOccurs="0" />
            <xs:element name="id" type="xs:string" minOccurs="0" />
            <xs:element name="outlineNumber" type="xs:string" minOccurs="0" />
            <xs:element name="initialEstimate" type="xs:string"
              minOccurs="0" />
            <xs:element name="linkedRevisions" type="LinkedRevisionList"
              minOccurs="0" />
            <xs:element name="linkedRevisionsDerived" type="RevisionList"
              minOccurs="0" />
            <xs:element name="linkedWorkItems" type="LinkedWorkItemList"
              minOccurs="0" />
            <xs:element name="location" type="xs:string"
              minOccurs="0" />
            <xs:element name="module" type="xs:string"
              minOccurs="0" />
            <xs:element name="plannedEnd" type="xs:dateTime"
              minOccurs="0" />
            <xs:element name="plannedStart" type="xs:dateTime"
              minOccurs="0" />
            <xs:element name="planningConstraints" type="PlanningConstraintList"
              minOccurs="0" />
            <xs:element name="previousStatus" type="Option"
              minOccurs="0" />
            <xs:element name="priority" type="Option"
              minOccurs="0" />
            <xs:element name="project" type="Project"
              minOccurs="0" />
            <xs:element name="remainingEstimate" type="xs:string"
              minOccurs="0" />
            <xs:element name="resolution" type="Option"
              minOccurs="0" />
            <xs:element name="resolvedOn" type="xs:dateTime"
              minOccurs="0" />
            <xs:element name="severity" type="Option"
              minOccurs="0" />
            <xs:element name="status" type="Option"
              minOccurs="0" />
            <xs:element name="timePoint" type="TimePoint"
              minOccurs="0" />
            <xs:element name="timeSpent" type="xs:string"
              minOccurs="0" />
            <xs:element name="title" type="xs:string"
              minOccurs="0" />
            <xs:element name="type" type="Option" minOccurs="0" />
            <xs:element name="updated" type="xs:dateTime"
              minOccurs="0" />
            <xs:element name="workRecords" type="WorkRecordList"
              minOccurs="1" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="customFields" minOccurs="0"
        maxOccurs="unbounded">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="field" minOccurs="0" maxOccurs="unbounded">
              <xs:complexType>
                <xs:complexContent>
                  <xs:extension base="CustomFieldValue">
                    <xs:attribute name="id" type="xs:string" />
                    <xs:attribute name="name" type="xs:string" />
                  </xs:extension>
                </xs:complexContent>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
 
  <xs:complexType name="CustomFieldValue">
    <xs:choice>
      <xs:element name="string" type="xs:string" />
      <xs:element name="boolean" type="xs:boolean" />
      <xs:element name="currency" type="xs:decimal" />
      <xs:element name="date-time" type="xs:dateTime" />
      <xs:element name="duration" type="xs:string" />
      <xs:element name="enum" type="Option" />
      <xs:element name="integer" type="xs:integer" />
      <xs:element name="multi-enum" type="OptionList" />
      <xs:element name="text" type="Text" />
      <xs:element name="time" type="xs:time" />
      <xs:element name="date" type="xs:date" />
      <xs:element name="float" type="xs:float" />
    </xs:choice>
  </xs:complexType>
 
  <xs:element name="workItems">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="workItem" minOccurs="0" maxOccurs="unbounded"
          type="WorkItem" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>
 
</xs:schema>

            

Internally Defined Work Item Metrics

This topic lists the default set of internally defined Work Item metrics for projects contained in the workitem-metrics.xml file. Any of these may be removed or commented out in the configuration file if you don't want the metric to be calculated For information about configuring Work Item metrics, see Administrator's Guide: Configuring Reports: Work Item Metrics.

Table 1.26. Internally Defined Work Item Metrics

NameKEYTypeDescription
Resolved vs. UnresolvedRESOLVED-UNRESOLVEDdistribution Counts resolved (subkey RESOLVED) and unresolved (subkey UNRESOLVED) Work Items in the project.
Unresolved By AssigneeUNRESOLVED-BY-ASSIGNEEdistributionCounts unresolved Work Items for every assignee in the project. Subkeys are User IDs.
Unresolved by CategoryUNRESOLVED-BY-CATEGORYdistribution Counts unresolved Work Items for every Category in the project, and also Work Items with no assigned Category. Subkeys are Category IDs, and _uncategorized.
Unresolved by Time PointUNRESOLVED-BY-TIMEPOINTdistribution Counts unresolved Work Items for every Time Point in the project, and also Work Items with no Time Point set. Subkeys are Time Point IDs, and _unscheduled.
Most Assigned to an Individual MAIintegerCounts the highest number of Work Items assigned to a single user. The rendered value includes the name of that user).
Most Entered by an IndividualMEIintegerCounts the highest number of Work Items created by a single user. The rendered value includes the name of that User.
Most Solved by an IndividualMSIintegerCounts the highest number of resolved Work Items assigned to a single user. The rendered value includes the name of that User.
Estimate AccuracyESTIMATE-ACCURACYpercentage Calculates accuracy of Initial Estimate values of individual Work Items in this way:
  • Finds all Work Items that have a value set for Initial Estimate, plus a value set for at least one of Time Spent and Remaining Estimate.

  • Sums all the Initial Estimate values (TOTAL_INITIAL).

  • Sums absolute values of differences... initialEstimate - (timeSpent + remainingEstimate) (TOTAL_DIFFERENCE).

  • Finally, accuracy is calculated as TOTAL_INITIAL / (TOTAL_INITIAL + TOTAL_DIFFERENCE). The higher the accuracy value, the better.

Project Plan AccuracyPROJECT-PLAN-ACCURACYpercentage Calculates overall accuracy of time estimates in the project in this way:
  • Finds all Work Items that have a value set for Initial Estimate plus a value set for at least one of Time Spent and Remaining Estimate.

  • Sums all the Initial Estimate values (TOTAL_INITIAL)

  • Sums all values for Time Spent and Remaining Estimate (TOTAL_ACTUAL)

  • Finally, accuracy is calculated as TOTAL_INITIAL / TOTAL_ACTUAL, if TOTAL_INITIAL < TOTAL_ACTUAL, or as TOTAL_ACTUAL / TOTAL_INITIAL, if TOTAL_INITIAL > TOTAL_ACTUAL. The higher accuracy value, the better.

Planning AccuracyPLANNING-ACCURACYpercentage Calculates percentage of unresolved Work Items having Time Point set, that are assigned to a Time Point that is not yet past, counting all unresolved Work Items with Time Point set (PLANNED), and counting how many of them are assigned to a Time Point ending before the current day (DELAYED). Calculates the value as PLANNED - DELAYED / PLANNED.
Estimated vs. Not Estimated Work ItemsPLANNING-COVERAGEdistribution Calculates number of estimated (subkey planned) and not estimated (subkey not-planned) Work Items. Work Item is estimated if it has a value set in Initial Estimate and at least one of Time Spent and Remaining Estimate.
In Time vs. Underestimated Work Items WORKITEMS-PLANNING-ACCURACYdistribution Rate of In-time (subkey correct) vs. underestimated (subkey incorrect) Work Items. (On time means that Initial Estimate >= Time Spent + Remaining Estimate). Only Work Items having a value set for Initial Estimate and a value set for at least one of Time Spent and Remaining Estimate are taken into account in the metric.
Requirements with vs. without linked documentsTRACEABILITYdistribution Rate of requirements (Work Items of type Requirement) having at least one attachment or hyperlink (subkey traceableRequests) and without any attachment and hyperlink (subkey untraceableRequests).

In-place Defined Metrics

See Administrator's Guide: Configuring Reports: In-place Defined Metrics.

Project Group Metrics

Work Item metrics on Project Groups are not configurable. The following internally defined metrics are calculated for project groups:

Table 1.27. Internally Defined Work Item Metrics for Project Groups

NameKEYTypeDescription
All Work ItemsALLintegerCounts all Work Items in the project group.
Resolved vs. UnresolvedRESOLVED-UNRESOLVEDdistribution Counts resolved (subkey RESOLVED) and unresolved (subkey UNRESOLVED) work items in the project group.
Unresolved by ProjectUNRESOLVED-BY-PROJECTdistribution Counts unresolved Work Items in all projects in the project group (and in child project groups, if any). Subkeys are project IDs.
Unresolved by Child EntityUNRESOLVED-BY-ENTITYdistribution Counts unresolved work Items in all projects and project groups directly in a project group (but not in child project groups). Subkeys are project IDs or project group names.

To display a specific element in a chart, it is necessary to prefix the element key with the pound (#) character. For example, following will display everything from the resolved-unresolved fact base:

{line-chart:report-path=charts/workitems-trend.xml|items=workitems-trend-data:RESOLVED-UNRESOLVED/*|tags=14|width=100%|height=100%}
                    

However, if you want to reference a specific element in this fact base, only the unresolved items, for example, then the key must have the # sign prefix:

{line-chart:report-path=charts/workitems-trend.xml|items=workitems-trend-data:#RESOLVED-UNRESOLVED.UNRESOLVED|tags=14|width=100%|height=100%}
                    

Calculations and Facts

This section documents facts that can be displayed in dashboards and the calculations that can render them.

Fact Bases

This section contains reference information about Polarion fact bases.

processaudit/project-level/source-check-aggregate

This fact base is calculated by processaudit calculation.

Values available in the project scope:

  • overall-test-coverage: unit test coverage

  • overall-test-results: unit test success ratio

repo-analysis

This fact base is calculated by the repoanalysis calculation.

Values available in project and project group scope:

  • NOU: Number of Users - the number of users having a role in the project or in some project in the project group.

  • NOF: Number of Files - the number of files in the repository for the scope being reported.

Values available only in the project scope:

  • NOD: Number of Developers - where "developer" means the author of some commit to the repository.

  • NODD: Number of Developers for the past day

  • NODW: Number of Developers for past week

  • NODM: Number of Developers for past month

  • NOC: Number of Changes - where "change" means a commit in the repository.

  • NOCD: Number of Changes during the past day

  • NOCW: Number of Changes during the past week

  • NOCM: Number of Changes during the past month

  • NOC-BY-DEVELOPERS: Number of Commits by Developers - where "Developer" means the author of some commit to the repository.

  • MAD: Most Active Developer - meaning the Developer making the most commits to the repository.

  • LAT: Last Activity Time - meaning the time of the latest commit to the repository.

workitems-data

This fact base is calculated by the trackeranalysis and trackeranalysis-projectgroup calculations. The available values are those for Work Item Metrics

Trend Fact Bases

These parallel fact bases with trend data exist for each regular fact base listed in the previous section.

workitems-trend-data

Calculated by the trackeranalysis and trackeranalysis-projectgroup calculations.

Available values: Trends of all values from workitems-data fact base.

repo-trend

Calculated by the repoanalysis calculation.

Available values: Trends of particular values from the repo-analysis fact base.

Values available in the project scope:

  • NOC: Number of Changes ("change" means any commit in the repository)

  • NOCD: Number of Changes for Last Day

  • NOF: Number of Files (i.e. number of files in the repository)

  • NOD: Number of Developers ("developer" means author of some commit in the repository)

processaudit/project-level/source-check-aggregate-trend

Calculated by the processaudit calculation.

Available values: Trends of all values (and their properties) from the processaudit/project-level/source-check-aggregate fact base.

Values available in both project and project group scope:

  • test-coverage.ratio: test coverage (i.e. ratio of total lines of code to line of code covered by unit tests)

Values available in the project scope only:

  • test-sucess-ratio.ratio: test success ratio

  • test-sucess-ratio.testsCount: number of tests

  • test-sucess-ratio.errorsCount: number of errors in tests

  • test-sucess-ratio.failuresCount: number of failures in tests

Velocity Macros Location

Polarion provides a few default macros implemented in Velocity that address, for example, the display of signatures in LiveDocs.

These "built-in" Velocity macros are defined in [Polarion HOME]\polarion\plugins\com.polarion.alm.wiki_N.NN.N\src\main\webapp\templates\macros.vm

(Where wiki_N.NN.N contains a version specification such as 3.18.0).

Each section is implemented as a specific sub-macro. For example, if a developer wishes to customize a macro such as documentPanel, they can refer to the following definition:

#macro(documentPanel $showPending $approvedState)
<div>
 #renderProperties()
 \\
 
 #renderLastApproved($approvedState)

 #renderSignatures($showPending)
</div>
#end

Velocity Variables for Active Wiki Pages

The following table lists the Apache Velocity variables available during Wiki page rendering. Developers may use these for extending Polarion Wiki pages via the respective Polarion API classes and interfaces. Descriptions of classes and interfaces are available in the Javadoc provided with the API.

Table 1.28. Velocity Variables and Polarion API Classes

VariableAPI ClassNotes
$calendarToolcom.polarion.wiki.util.CalendarTool 
$documentcom.polarion.alm.tracker.model.IModuleOnly available on Wiki Content Blocks. (Not available for Wiki Pages.)
$me Available in Velocity context only. References the ID of the current user when used in a wiki page.
$pagecom.polarion.alm.wiki.model.IWikiPage 
$plancom.polarion.alm.tracker.model.IPlanAvailable on old wiki pages that were used as Plan pages.
$platformServicecom.polarion.platform.IPlatformService 
$projectServicecom.polarion.alm.projects.IProjectService 
$securityServicecom.polarion.platform.security.ISecurityService 
$testManagementServicecom.polarion.alm.tracker.ITestManagementService 
$testRuncom.polarion.alm.tracker.model.ITestRunAvailable on old wiki pages that were used as TestRun pages.
$trackerServicecom.polarion.alm.tracker.ITrackerService 
$transactionServicecom.polarion.platform.ITransactionService 
$wikiServicecom.polarion.alm.wiki.IWikiService 

Apache Lucene Options

Polarion uses an implementation of the Apache Lucene query engine to enable portal searches and Work Item queries. This section documents some properties which administrators can set in the polarion.properties system configuration file to control some behaviors of the embedded Lucene.

Table 1.29. 

PropertyDescriptionDefault Value

luceneMaxClauseCount

Defines how many OR/AND parts a query can have. This includes simple range queries which are expanded by Lucene internally to this form. Polarion itself needs such queries with many ORs when there are many links to a single Work Item (e.g. thousands).

20000

luceneMaxFieldLength

Defines the maximum number of terms that will be indexed for a single field in a Document. This means that object (e.g. Work Item) will not be searchable on words appearing too far from the beginning of the value of the field (e.g. description). Special example is artificial field in which words are searched during full text search. Value should be set to higher value in case there are errors logged: "Lucene: maxFieldLength 50000 reached, ignoring following tokens". It can be set to negative value to mean no limit. However, Lucene documentation says that OutOfMemory error can occur. (This has not been tested with Polarion).

When the value of this property is increased because of the occurrence of errors in the log, the system index must be refreshed in order to fix the index entries of truncated fields.

50000

License Usage Reference

The License page of Repository Administration shows current license usage information in the following tables:

Table 1.30. Concurrent License

ColumnDescription

Total

Maximum number of users than can access Polarion at the same time with concurrent license assigned

Configured

Number of users configured in the users file to share the licenses from the concurrent license pool

Free

Number of licenses from the pool that are not assigned to any user at the moment

Peak

Greatest number of concurrent licenses that were used at the same time

Table 1.31. Named License

ColumnDescription

Total

Number of named licenses that can be assigned to specific users

Configured

Number of licenses that are currently assigned to a user

Free

Number of licenses from that are not assigned to any user

Table 1.32. Usage Details

ColumnDescription

User

The user ID of a user who is currently using a license

Status

Status of the license used by Status

  • Active: user is logged in to Polarion and using a license

  • Waiting for expiration: user was using a concurrent license and has logged out, but the license is not yet returned to the license pool

License

Name and type of the license in use by User. (Type includes add-on licenses.)

Default Assignment of Concurrent Licenses

License assignment of concurrent licenses occurs in the following way:

  • Default license specified in the users file.

  • If not specified, then the license with highest number of concurrent slots.

  • If some licenses have the same highest number, then the lowest license that shares this highest number is assigned.

  • If all are zero, then no license is assigned.

Self-signed SSL Certificates

To use Polarion with SSL, you may opt to create and use a self-signed SSL certificate rather than using one from an authority trusted by Java. Using a trusted certificate is preferred and recommended. An untrusted certificate requires the additional configuration steps to import it to the Java keystore. See the Administrators Guide topic configuring Polarion to use SSL. This topic describes how to create a self-signed certificate on Linux and Windows.

Linux

The following example creates a certificate named serverCert.pem You can name the certificate file as desired.

    apt-get install openssl
    openssl req -x509 -nodes -days 3650 -newkey rsa:1024 -keyout serverKey.key -out serverCert.pem
                    

Note that depending on your operating system version, the above command may require some additional parameters.

Windows

The following example creates a certificate named serverCert.pem You can name the certificate file as desired.

Run the following command from the command prompt, as a single line:

openssl req -x509 -nodes -days 3650 -ewkey rsa:1024 -keyout privateKey.key -out serverCert.pem

You may need add -config [Polarion]\bundled\apache\conf\openssl.cnf in order to add the appropriate openssl.cnf - which is in Apache's conf directory (hidden .cnf suffix). Example:

openssl req -config D:\Polarion\bundled\apache\conf\openssl.cnf -x509 -nodes -days 3650 -newkey rsa:1024 -keyout privateKey.key -out serverCert.pem