Administrator and User Help
Administrator and User Help
This Documentation contains trade secrets or otherwise confidential information owned by Siemens Industry Software Inc. or its affiliates
(collectively, “Siemens”), or its licensors. Access to and use of this Documentation is strictly limited as set forth in Customer’s applicable
agreement(s) with Siemens. This Documentation may not be copied, distributed, or otherwise disclosed by Customer without the
express written permission of Siemens, and may not be used in any way not expressly authorized by Siemens.
This Documentation is for information and instruction purposes. Siemens reserves the right to make changes in specifications and other
information contained in this Documentation without prior notice, and the reader should, in all cases, consult Siemens to determine
whether any changes have been made.
No representation or other affirmation of fact contained in this publication shall be deemed to be a warranty or give rise to any liability of
Siemens whatsoever.
If you have a signed license agreement with Siemens for the product with which this Documentation will be used, your use of this
Documentation is subject to the scope of license and the software protection and security provisions of that agreement. If you do
not have such a signed license agreement, your use is subject to the Siemens Universal Customer Agreement, which may be viewed
at https://www.sw.siemens.com/en-US/sw-terms/base/uca/, as supplemented by the product specific terms which may be viewed at
https://www.sw.siemens.com/en-US/sw-terms/supplements/.
SIEMENS MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS DOCUMENTATION INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF INTELLECTUAL PROPERTY.
SIEMENS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, LOST DATA OR
PROFITS, EVEN IF SUCH DAMAGES WERE FORESEEABLE, ARISING OUT OF OR RELATED TO THIS DOCUMENTATION OR THE INFORMATION
CONTAINED IN IT, EVEN IF SIEMENS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
TRADEMARKS: The trademarks, logos, and service marks (collectively, "Marks") used herein are the property of Siemens or other parties.
No one is permitted to use these Marks without the prior written consent of Siemens or the owner of the Marks, as applicable. The use
herein of third party Marks is not an attempt to indicate Siemens as a source of a product, but is intended to indicate a product from,
or associated with, a particular third party. A list of Siemens' Marks may be viewed at: https://www.plm.automation.siemens.com/
global/en/legal/trademarks.html. The registered trademark Linux® is used pursuant to a sublicense from LMI, the exclusive licensee of
Linus Torvalds, owner of the mark on a world-wide basis.
User guide.........................................................................................................3-1
Reference.......................................................................................................... 6-1
Administration reference.............................................................................................. 6-1
Polarion folder structure..................................................................................................... 6-2
Passwords.......................................................................................................................... 6-5
Polarion system processes...................................................................................................6-6
System configuration properties file location....................................................................... 6-7
Scheduler cron information and examples...........................................................................6-8
Permission Management.................................................................................................... 6-9
Dynamic roles and permissions......................................................................................... 6-13
Default Enumeration configuration files............................................................................ 6-22
Notification events and targets..........................................................................................6-23
Custom field types............................................................................................................ 6-31
Build configuration file format...........................................................................................6-35
Work report Job configuration...........................................................................................6-36
Workflow Conditions and Functions for Work Items........................................................... 6-37
Workflow Conditions and Functions for Documents...........................................................6-44
Workflow conditions and functions for Test Runs...............................................................6-49
Workflow error handling................................................................................................... 6-53
Scripting engines and languages.......................................................................................6-54
Scripted Workflow Functions and Conditions..................................................................... 6-56
On-demand Work Item loading......................................................................................... 6-59
Polarion and system log files............................................................................................. 6-61
XML export schema.......................................................................................................... 6-64
Internally defined metrics .................................................................................................6-72
Calculations and facts....................................................................................................... 6-76
Velocity macros location................................................................................................... 6-79
Velocity variables for Active Wiki Pages............................................................................. 6-80
Apache Lucene options.....................................................................................................6-82
License usage reference....................................................................................................6-83
Self-signed SSL certificates................................................................................................ 6-85
Glossary............................................................................................................ 8-1
Work with Tests Test Cases in the tracker Custom Work Item fields
View source code and JavaDocs Link Test Cases Automatic assignments
This documentation covers all features of Polarion ALM. However, depending on your license, some of the
features described may not be available to you.
Polarion Variants: This add-on provides a back-end server component which, when combined with
capabilities built into some project templates, adds robust variant management capabilities to the above
products.
Installation documentation
PDF and HTML versions of the Deployment and Maintenance Guide can be found on Support Center.
Extensions
If default functionality doesn't fully meet your needs, you may find a solution on the Polarion ALM
Extensions web portal. There you will find a catalog of useful extensions for Polarion ALM, ranging from
utilities to project templates, to complete features.
The Extensions portal is located at: https://extensions.polarion.com. You can click the Extensions link in
the tool view of Navigation to visit the site.
Administrators must perform the following tasks when configuring user accounts:
• Configure Polarion so that users can create their own Polarion accounts.
• Configure Polarion to work with one or more of the following external authentication providers:
◦ LDAP
◦ OAuth 2
◦ SAML
Administrators can configure Polarion to let new users create their own user accounts. If configured, a
Create your Polarion Account link appears in the logon screen.
Procedure
2. In the form, specify your account credentials such as user name, password, and email address for
receiving notifications.
Caution
The characters allowed in passwords depend on how your system is configured to authenticate
users. The safest approach is to use only ASCII characters in passwords excluding the double-quote
A logon screen appears and you can log on with your credentials.
Tip
When you create an account this way, you have basic read access to the system, but you may not have
access to all the information or all the actions you need. For example, you may not be able to open
some projects, create new projects, or edit Work Items or Documents. The information you can access
and the actions you can invoke depend on how your administrators configured default permissions for
user-created new accounts. You may need to coordinate with an administrator to review and modify
your permissions.
Log on
Polarion has a web-based user interface. There is no local client application — you only need a supported
web browser. Your administrator or other designated person should provide you with information about
browsers and the access URL of your company's Polarion system.
If you are not already logged on, then when you access any URL in the system, the logon dialog box
appears. In most cases, you only need to enter your user name and password.
Tip
Polarion usernames are case insensitive on logon. The same user can log on as user1, USER1 or UsEr1.
If your system is configured with multiple Polarion servers, the logon dialog box indicates which server you
are currently accessing, and then displays a link Change Server that enables you to select the server you
want to access and log onto.
The first time you log on, you see the home page of the server and the word Repository appears in
Navigation indicating the scope in which you are now working. On subsequent logons, Polarion opens the
project, the Navigation topic, and the page you were viewing when you logged off.
Tip
If your company uses a centralized user authentication system, and has configured Polarion to work with
it, you may not be able to modify some or all of the personal information fields on your user account
page. The following procedures assume that user authentication is configured to allow editing of the
data. If you are not able to make needed changes on your user account page, contact your Polarion
administrator.
Procedure
Procedure
1. On the page toolbar, click Edit to reveal the hidden password fields.
2. In the New Password field, type the new password you want to use.
3. Enter the new password again in the Re-enter Password field.
4. Click Save to save the changes.
The new password takes effect the next time you log on.
Caution
The characters allowed in passwords depend on how your system is configured to authenticate users.
The safest approach is to use only ASCII characters in passwords excluding the double-quote character
("), which is not allowed by Polarion. If you need to use non-ASCII characters in your password, consult
your administrator before changing it.
Procedure
1. Hover your pointer over the Email field and click it. You can now edit the field.
2. Replace the existing email address with the new email address you want to use.
Tip
Email notifications from the Polarion system are sent to this address. If you do not want to receive
notifications you can select the Disable Notifications check box.
Procedure
1. Hover your pointer over the Name field and click it. You can now edit the field.
2. Replace the existing name with the new name you want to use.
Tip
The name you enter here appears in Navigation when you are logged on and in the list of all users.
It appears to other users in various places, for example, the Assignee field of Work Items assigned
to you.
3. If you want to change your initials, click the Initials field and change the value.
4. Click Save to save the changes.
You can change the avatar image that displays next to your name in Navigation when you are logged on,
in Activity Stream activities, and other system objects your work generates. The procedure is explained in
the topic Your personal Home page.
Tip
Be sure the page is not in edit mode. If it is, the link enabling you to change the image is hidden.
Tip
You might opt to disable notifications temporarily, for example, during vacation or holiday time.
Procedure
1. Log on to the portal, and in Navigation click Actions to switch to the tool view.
2. Click My Account. The user account page opens.
3. On your user account page, select the Disable Notifications option, and then click Save.
If you encounter any of the following or similar problems, the most likely reason is that you are not
currently granted the requisite permissions:
To create new projects your user account must be assigned a user role which has been granted that
permission. If your system is configured to support multiple repositories, you must have the necessary
permissions for the repository that hosts the new project.
User permissions are defined in the User Management topic of Administration, and configured by
administrators. If you cannot create, modify, or view any content that you believe you should have access
to, either contact your administrator directly or follow whatever contact chain your team or organization
has established.
If your organization uses this feature for project planning, management, and reporting, you should
check your personal User Calendar before you begin processing Work Items. Your User Calendar tells
the system the days and hours you normally work, and enables you to report exceptions to that, such
as vacation, leave, or other planned time off. This information is available in the system for calculations
related to project status and planning reports. The global Working Calendar is configured by a Polarion
administrator, and it defines the standard working time, holidays, and so forth for your company. This
information appears by default in your User Calendar.
You only need to change your User Calendar when your work schedule differs from that defined in the
global Working Calendar. You can specify personal time off such as vacations, or leaves of absence. You can
also log temporary schedule differences. For example, if you plan to take several hours per week off over a
period of 3 months to attend some classes, you can configure your User Calendar to reflect this.
Your User Calendar is available on your user profile page. Access this page by clicking the My Account
link in the tool view of Navigation. Scroll the page until you find User Calendar. Click it to load your User
Calendar. You can use the set of graphical controls to make and save changes to your User Calendar.
The Regular Schedule section lists the working days and times of your normal work schedule. By default,
the values are from the global Working Calendar. If your regular working time differs from the global
schedule on one or more working days, you can change the start and end time for the affected day(s).
Procedure
1. Select the check box beside the day you wish to change. This enables the override of the global
Working Calendar. The Start Time and End Time boxes are now editable.
2. Change the Start Time and/or End Time value(s) as desired.
3. Click Save in the toolbar above the section.
Tip
You can mark any day in the Regular Schedule section as a nonworking day by clicking the icon after
the End Time field.
Suppose you changed the start and/or end time for several week days in your Regular Schedule because
you were working only part time, and now you have started working full time and want to sync your User
Calendar back to the global schedule. To do this, clear the check box next to the modified work day(s) and
save the change.
Schedule exceptions
In the Schedule Exceptions section, you can define exceptions to the regular schedule. Exceptions can be
permanent, or temporary for a specific period of time. For example, suppose you take time off for a holiday
that occurs on the same date every year. This can be set up as a permanent exception to your normal work
schedule. If such a holiday falls on a different date each year, it can be set up as a temporary exception.
• Time Off: The exception is time that will not be available for work in addition to any nonworking time
configured in the Regular Schedule.
• Time Working: The exception is time that will be available for work in addition to the working time
configured in the Regular Schedule.
Procedure
1. Enter a meaningful title for the exception in the Title field, for example, New Years Day Holiday.
2. Select the exception type by choosing a value in the Type drop-down list, for example, Time Off.
3. Specify the date when the schedule exception is to begin in the Date From field in this format:
yyyy-mm-dd. Alternatively, click the calendar icon next to the field and choose a date in the pop-up
calendar, for example, 2008-01-01.
4. If the exception you are defining is temporary, specify the date when it should end in the Date To
field, in the same format as mentioned in the previous step. For a one-day exception like our New
Years Day example, the value should be the same date as in the Date From field. If the exception is
ongoing, leave the Date To field empty.
5. If the exception you are defining occurs only on one specific weekday in the time period defined,
choose that day in the drop-down list in the Weekday column. Otherwise, leave the default value All
days.
6. If the exception you are defining is of the type "Time Working", set appropriate time values in the
Time From and Time To fields, which are enabled when this type is selected. Time From is the time
when the additional working hours start, and Time To is the time when the additional working hours
finish.
7. If you want to add another Schedule Exception, click in the Actions column and repeat the above
steps on the new row that appears.
8. When you are finished defining your Schedule Exception(s), click Save in the Working Calendar
toolbar. To cancel all changes, click Revert.
Procedure
The Navigation Header at the top displays what artifact you are currently working in and the project that
it belongs to.
Tip
• Administrators can customize the Create button and the artifacts users can Quick Create from the
Navigation Header.
• Administrators, (or the user that created a project) can also select a custom project icon for the
Navigation Header.
The Navigation panel occupies the left side of the Polarion portal page. By default it displays the Topics
view which shows the topics available to you under the product license you are using.
Note
When you first log on, if the product you are using is not yet licensed for production, the log on screen
offers the option of running with a built-in evaluation license, or activating the installation online or
offline. After a license is in place, you enter the portal and can begin navigating around to different
areas.
Topics provide access to various feature and content areas and to Shortcuts, which quickly retrieve sets of
Work Items together with their context. Some Topics expand and have subtopics that either narrow the
scope of the information shown or provide access to additional functionality. There are a number of ways
you can Personalize Navigation.
You can easily hide the Navigation panel using the icon in the upper right corner of the panel. When the
panel is hidden, you can restore it by clicking the left border of the page as shown in the figure below.
The Topics are specific to the information scope in which you are working — repository, project group,
or project. The topics shown may also vary according to the interface view you are using. Polarion
administrators can define and customize Interface views. If you have permissions for Administration,
only administration and configuration topics are shown when you access it.
You can create Favorites and Shortcuts in the Navigation panel that take you quickly into the key things
you need to access in the project such as Documents, Pages, Work Items, and Dashboards.
Navigation has two views — Topics and Tools. The Topics view is shown by default.
The Tools view of Navigation provides access to some things that are usually needed only occasionally.
You can change the level of detail displayed on a Work Item using the button on the Work Item
toolbar.
Which fields are displayed or hidden can be defined by an administrator in the Form Filters section of
Form Configuration.
The lower portion of the panel provides information about the Polarion system, such as license type and
build number. Also provided are links that enable you to send feedback to the development team, contact
technical support, and visit the extensions portal.
Note
As of Polarion 21 R1, the Send Feedback link is unavailable in navigation by default, but administrators
can enable it by adding the following property to the polarion.properties file with a target email or
hyperlink.
com.siemens.polarion.feedback.link
The rest of the portal page is the area where you work with the various Polarion features. Pages provide
access to the content and features of the Navigation topics like Documents, Pages, Dashboards, and
Builds. What displays in this pane depends on a number of factors, including current information scope,
currently selected Shortcut or current Work Item query, and whether your are working in Administration.
Changing the View lets you alter the way Polarion is displayed.
When you change the View you can select between both:
Procedure
2. Click View.
3. Click a view.
Compact view reduces the amount of white space and extension title size in the user interface.
Normal view:
Tip
See Change the view to change between Normal and Compact view or Normal and High Contrast
views.
Compact view:
High contrast view adds solid and dotted lines to Document changes so that people with color visual
impairments can easily identify changes.
Tip
See Change the view to switch between Normal and High contrast or Normal and Compact views.
Navigation topics
The Navigation panel presents various Topics, which are descriptive links leading to content and features.
Not all topics listed are available with every product license. Where availability is limited by license, this is
noted.
Note
Even if the product license makes a topic available, it may be hidden in the interface view you are using.
If you miss a topic you think your license should provide, try switching to another interface view by
clicking the icon in Navigation, and then clicking View.
The Home topic of every project, project group, and Repository displays a special Home page. Polarion
provides some default content in these pages, which varies depending on the scope you are currently
viewing — Repository, project group, or project. Users can, and normally do, modify Home pages to
provide information that is useful for team members and stakeholders working in the respective scope.
You can learn how to modify page content in the topic Working With Pages.
The Documents and Pages topic provides access to the Documents and Pages belonging to the current
repository or project. In the Repository scope, it's a good place to create content that all portal users might
need to access. In the project scope, the information created in this topic should be relevant for project
stakeholders.
When you expand the Documents and Pages topic in Navigation, you see a listing of the spaces,
Documents, Pages, and Classic Wiki pages in the current scope, unless there are too many to display
comfortably. In that case, you see a prompt to use the search field that appears at the top of the
Navigation panel. Enter a word or phrase you want to locate, and select the content type. Filter results
appear incrementally as you type.
Documents
Documents provide an easy, familiar way to author, collaborate on, and share content online. Documents
can contain Work Items which can be managed throughout a process as artifacts using all available tools,
while remaining in an easy to use online Document.
Pages
Pages differ from Documents in that they do not contain Work Items such as requirements and test cases.
However, Pages can show information about Work Items.
Work Items
The Work Items topic provides access to the integrated tracker. The topic is available for Repository,
project group, and project scopes. This topic provides access to all the Work Items in the selected scope.
You can select different views of these Work Items using the view selector control on the toolbar of the
Work Items page. Depending on the license you are using, not all these views may be shown on the menu.
Plans
The Plans topic provides release management tools and enables access to the release plans in the
current project or the entire repository. Plans enable teams to define Iterations and Releases. For both of
these, the team can set the start and end dates, specify which Work Items are to be implemented, and
monitor progress in near real time via built-in charts.
Plans provide visibility on status and progress for all stakeholders and can reveal potential risks and blocks,
so managers can make adjustments to the work scope, delivery date, resources, and other parameters.
Test Runs
The Test Runs topic provides access to Test Runs. Test Runs encapsulate a set of test cases and record
an instance of execution of each test case along with its status. You can create Test Runs for both manual
and automated tests. To browse Test Runs, you must have read permission for Test Runs. To create new
Test Runs or perform manual type Test Runs, you must use a license for a product having test management
support, and you must have the requisite permissions for the operation.
This topic also provides access to Test Run templates, and to Round-trip for Microsoft Excel. Test Run
templates store information about the Test Cases to be run, the tested build, testing environment, and
other information. Excel Round-trip enables exporting a Test Run's Test Cases to Excel for sharing with
external testers and reimporting of testing results logged by external testers in Excel into the Test Run.
Baselines
The Baselines topic enables you to see and compare existing Project Baselines, and also create new
ones. Project Baselines are basically snapshots of the status of a project some point in time. By creating
such baselines periodically and comparing them, it is possible to gauge the progress of a project over time.
The Time Machine feature enables you to load a Project Baseline and browse it just as if it were the current
state.
Tip
Project Baselines are distinct objects from Document Baselines.
Collections
Collections support parallel development activities, help with audit and regulatory compliance and
support advanced reuse scenarios. They are more than just containers for Documents. If you heavily reuse
Documents, you can create a Collection to support parallel development activities and help with audit
and regulatory compliance. See What is a Collection for more information.
Dashboard
The Dashboards topic provides status information through charts, metrics, and reports. Depending on
the scope you are working in, the status is compiled for the current project, all the projects in a project
group, or all the projects in the entire repository. Dashboard information is rolled up from repository data
that is automatically tracked in real time as teams work on projects, create or complete Work Items, and
adjust project plans.
Managers can decide how often the status information should be updated, and administrators can create
scheduled jobs to update dashboards at less busy times when more system resources are available. Users
with the requisite permissions can explicitly invoke a dashboard update to see the up-to-the minute state
of a project or projects.
Quality
The Quality topic centralizes the live dashboards that report metrics related to software quality.
This topic can be useful if you use Polarion for Quality Assurance.
Reports
Note
This feature is also available with a Requirements license, but it is hidden in the default configuration. An
administrator can modify the Navigation configuration to show it.
The Reports topic provides access to several reports related to project source code, including unit
tests, test coverage, and Javadoc for Java projects, and also provides read access to source code files. You
can explicitly launch report calculation from this topic as well.
Builds
Scope: Project
Note
This feature is also available with a Requirements license, but it is hidden in the default configuration. An
administrator can modify the Navigation configuration to show it.
The Builds topic enables you to access the current and recent builds of any project. You can find
information about build jobs, create a new build, and access the build results.
Monitor
The Monitor topic provides access to information about current and scheduled jobs and, for users with
permissions, the possibility to create and launch jobs. Jobs are background processes run on the server that
run various operations such as updating a dashboard.
Repository Browser
The Repository Browser topic provides access to an integrated Subversion client. This client enables
you browse the content of the Subversion repository that is installed and used with Polarion by default.
You cannot use this client with any external Subversion repository configured in the Repositories topic of
Administration or with any other version control system that may be custom implemented as the default
Polarion repository.
If your system is configured with multiple Polarion instances, the Repository Browser accesses the default
Subversion repository on the server you are currently using. In addition to browsing the repository, the
Repository Browser can perform limited basic repository operations such as adding files, managing folders,
and committing changed files. It is not designed to replace a full-featured Subversion client.
Shortcuts Topics
The Navigation panel contains three topics that provide Shortcuts. Shortcuts are special saved queries
which retrieve both data and some presentation of the data. They provide quick access to frequently-
needed information in the Polarion portal regardless of where you are working at the moment. The three
top-level shortcuts topics are:
• Global Shortcuts: These shortcuts are available to all portal users. The shortcuts found under this
topic must be configured by a global administrator.
• Project Shortcuts: These shortcuts are available to all users working in a specific project. Each project
can have a different set of shortcuts. Project shortcuts can be configured by a project administrator in
Administration. Project users with appropriate permissions can create project shortcuts by saving the
results of some query as a shortcut and specifying that the shortcut should be saved in the project
scope.
• User Shortcuts: This topic is empty by default. You can create shortcuts for your personal use by
saving the results of a query as a shortcut and specifying that it should be saved as a user shortcut. User
shortcuts that you create are not visible to other users.
Don't confuse User shortcuts with Favorites. Favorites are accessible only in the project where you create
them, and navigate only to content of that project. User shortcuts can be defined to navigate you to
anywhere in the portal from anywhere in the portal.
Shortcuts can help you personalize Navigation and quickly search for Work Items you need to refer to
often.
Related Topics
Search Polarion
Your starting point for content search is the search field in Navigation. Type in a word or phrase you want
to search for. You can search Navigation content, current project content, and portal content. You can
restrict and refine your search results.
Start Restrict search to a selected topic. Refine results. (Displays all results
Selectable topics will vary depending on regardless of topic configuration.)
your configuration. (Hidden topics are
not included.)
Navigation Content
When you begin typing a search term, the initial scope is Navigation. For example, if you type the word
"Developer" and Navigation contains a Page title Developer Guidelines and a Document title Developer
Documentation, both these items appear as clickable labels. Essentially you are filtering Navigation for the
search term.
You can restrict the Navigation search results to a specific content type:
• Work Items
• Documents
• Collections
• Wiki
• Pages
• Plans
• Test Runs
• Attachments
Restricting a search to a content type is useful if your search term returns many items. Choosing one of the
content types shown in Navigation when search is active limits the results to the selected type. Following
the example above, if you type the word "specification" and select Documents, only the pages shown
above in the Documents section of the search results page appear in the results.
Project Content
When you are working in a project, you can enter a search term in the Search field and press Enter or
Return to search the project content. The search results appear in a results page, which is divided into
sections for different topic types.
(Work Items, Documents, Collections, Wiki, Pages, Plans, Test Runs and Attachments.)
The Search Results page has links that filter for specific content types or change the sort order of the
results. All individual results are links that take you to the respective content.
Portal Content
There are several ways you can search the entire portal:
• Open the Repository, enter a search term in Navigation, and press Enter or Return.
• When working in a project, enter a search term in Navigation, hold Shift and press Enter or Return.
• In the Search Results page of a project-scope search, click Everywhere to search the entire portal for
the term used in the project-scope search.
Tip
If you switch from a project to the repository or vice versa, the scope of the search for the current string
changes according to where you are, but your search string remains in effect until you change it.
If you search for attachments, the search results show the parent object such as a Work Item or
Document that contains each found attachment. You can then download found attachments from the
search results.
Index fields let you refine searches so that they only return results with the artifacts you are looking for.
Artifact index fields get indexed by Polarion's search engine, so you can use them to improve the accuracy
and efficiency of your searches.
• Attachments
• Documents
• Pages
• Plan
• Test Runs
• Wiki Pages
• Work Records
• Work Items
Tip
See Work Item and index fields for more information.
(sortable)
attachments.author.name
(sortable)
attachments.content
(tokenized)
attachments.fileName
(tokenized)
attachments.length
attachments.length.1 (one
word)
(sortable)
attachments.title
(tokenized)
attachments.updated
(sortable)
Backlinked Derived field backlinked backlinkedWorkItems via
Work Items containing links WorkItems
pointing from other linked
Work Items to the (All one word) WorkIte
referenced one (e.g. ms
WI-1). These links are
not stored in the WI-1 (All one
item, but are displayed word)
in the Linked Work
Items section of WI-1.
Categories This field enables categories categories.id yes
you to flexibly
categorize Work categories.name
Items according to
subsystem, customer,
See: Configure
Categories.
Comments This multiple entry comments comments.author.id yes
field stores free-form
text comments. Users comments.text
can create multiple
Comments and (tokenized)
Comment threads in
this field throughout
comments.title
the life of a Work
Item.
(tokenized)
Created The date a Work created created (date only) perman
Item was created. ent
The non-editable date created.1 (datetime)
value of this field is
automatically assigned created.2 (sortable)
by Polarion and
appears in the footer
of the Work Item
Editor
Custom Field Custom Fields can be customFieldI customField (tokenized) yes
defined by d
(general) administrators in customField.1 (sortable)
Administration
Work Items Custom customField.KEY
Fields. There are
different types of
custom fields such as
string, text,
enumerations, etc. All
custom fields use
(hostname)
Hyperlinks Field that stores hyperlinks Not searchable yes
hyperlinks to other
resources inside the
Polarion portal, or
remote (internet URLs,
for example)
Time duration is
specified by an integer
value, or the literal
1/2 (or any other
fraction). Examples:
• 3d - 3 days
• 7h - 7 hours
• 1/2d - 1/2 day
Linked Field that stores links linkedRevisi linkedRevisions yes
Revisions to repository revisions ons
that are stored with
the Work Item.
(All one
word)
Linked Work Field that stores linkedWorkIt linkedWorkItems yes
Items links to other Work ems
Items, either in the Uses special syntax.
same repository or
another repository See Query for Linked Work
hosted on another Items.
Polarion instance (if
the system is so
configured).
Location Field that stores location location no
repository ID and
path where the location.tokenized
Work Item is stored
in the repository. (tokenized)
Can be used e.g.
to filter only items
location.tree
that are contained
in Documents from
certain space.
Outline A derived field that outlineNumbe outlineNumber yes
Number stores the outline r
number of a Work Uses special syntax.
Item, if the item
is contained in a See Query for Documents.
Document. Users can
search Work Items
by outline numbers Note
(also works for partial By default, it is only possible
searches, e.g. 1-2*). to query on, or sort by Work
Item Outline Number in the
HEAD revision because the
historical index for this field is
disabled by default. For more
information, see Search by
Outline Number in historical
revisions.
parentWorkItem:
ProjectId/WorkItemId
Time duration is
specified by an integer
value, or the literal
1/2 (or any other
fraction). Examples:
• 3d - 3 days
• 7h - 7 hours
• 1/2d - 1/2 day
Resolution Indicates the final resolution resolution yes
outcome of a Work
Item. The default resolution.1
values are defined
in the global and/or (sortable)
project configuration.
Keep in mind that
values in projects
may be from the
Project Template from
which the project
was derived. Also
keep in mind that
the visibility of the
field and/or the ability
to change the value
may be controlled
by the workflow
configuration and
bound to change of
the Status field.
In the default
configuration for this
field, the IDs of
Work Items with high
severity appear in
Red font in the user
interface.
Configure
Enumerations.
Time duration is
specified by an integer
value, or the literal
1/2 (or any other
fraction). Examples:
• 3d - 3 days
• 7h - 7 hours
• 1/2d - 1/2 day
Title Each Work Item title title perman
receives a unique ent
ID automatically so (tokenized)
Title should contain
a short description title.1
of the Work Item.
The item can be
(sortable, lowercase)
described further in
the Description field.
updated.2
(sortable)
WatchedBy Lets you search for watchedBy yes
Work Items watched
by a specific user.
(watchedBy:userna
me)
Work Records Field that stores work workRecords workRecords yes
records. Work records
record blocks of time (stores dateonly-userId)
spent working on the
Work Item. workRecords.user.id
(tokenized)
workRecords.comment
(tokenized)
Quick Create
Quick Create lets you create artifacts wherever you are in Polarion from the Navigation Header.
Tip
Quick Create comes preconfigured in Polarion (22 R2 or later), but Administrators can completely
customize it.
Procedure
Note
The button name may differ depending on how your Polarion administrators' configured the
feature.
Available options depend on the template the project is based on and how your Polarion
administrators' configured the feature.
The creation dialog for your selected artifact appears.
3. Enter your artifact's details and click Save on the top left.
Your artifact is created in the selected project and its name appears in the Navigation Header.
Create a project
Project Templates
Polarion comes with several default project templates designed to provide artifact types, workflows,
system configurations, and content that support different types of projects.
Looking into project templates should be a project manager's first step in planning for a new project. There
is a good chance that one of the available templates provides everything needed for your project. A good
way to check this is to create sandbox projects on your own Polarion server. Create test projects using the
templates that seem closest to what you need, and then look at them in terms of the issues discussed in
the following topics to see if the template provides what you need. If the template doesn't provide what
you need, determine what you might need to customize to get you there.
To learn how to create a project using a project template, see Create a New Project From a Template. To
learn about customizing project templates, see Customize Project Templates.
Tip
You can download additional templates from the Polarion Extensions portal and administrators can
customize existing project templates and upload them.
This Agile-based, Project Template supports the full software application lifecycle from start to finish.
It includes the management of product and release backlogs, sprint management and reporting, and test
management with full quality assurance coverage. It has a standard Java project structure that supports
the automated build process managed by Maven-2.
Work Items
Task
Link Roles
Workflow
Change Request
Link Roles
Workflow
Epic
Link Roles
Workflow
Issue
Link Roles
Workflow
Release
Link Roles
Workflow
Requirement
Link Roles
Workflow
Test Case
Link Roles
Workflow
User Story
Link Roles
Workflow
A V-Model (Waterfall) based Software Engineering Project configured for Feature, Requirements, and Test
Specifications that includes Variant Management with propagation. Project with Demo Data: Weather
Station
Work Items
Test Case
Link Roles
Workflow
Feature
Link Roles
Workflow
Requirement
Link Roles
Workflow
Variant
Link Roles
Workflow
A V-Model-based Software Engineering Project configured for Requirements and Test Specifications that
includes Teamcenter Variant Management with propagation.
Tip
The Teamcenter Product Configurator lets you manage your variant data independently across
multiple applications, including Polarion.
See the Teamcenter Configurator integration topic for configuration settings and additional
information about this template.
Requirement Workflow
This project is based on the Specification Project with Variant Management template with additional
sample data. Use this template to instantiate your own copy of the Weather Station demo project.
Work Items
Variant
Link Roles
Workflow
Feature
Link Roles
Workflow
Requirement
Link Roles
Workflow
Test Case
Link Roles
Workflow
V-Model Project
Project with Demo Data: Drive Pilot: A V-Model (Waterfall) based Project template that supports the full
application lifecycle. It provides all that's needed to determine and define requirements, design then assess
the risks, plan the development, monitor the development process, test the results and maintain your
product. It has a standard Java project structure that supports the automated build process managed by
Maven-2.
Work Items
Risk
Link Roles
Workflow
Change Request
Link Roles
Workflow
Issue
Link Roles
Workflow
Software Requirement
Link Roles
Workflow
Release
Link Roles
Workflow
Link Roles
Workflow
System Requirement
Link Roles
Workflow
Link Roles
Workflow
Task
Link Roles
Workflow
Test Case
Link Roles
Workflow
Link Roles
Workflow
Work Package
Link Roles
Workflows
V-Model Project QA
A V-Model (Waterfall) based Project template that includes: Requirement Specifications and their formal
approval along with Risk and Test management. You can start by filling in the Requirement Specification
documents, then target requirements for release and analyse potential risks by using the FMEA Worksheet
templates. Then it's time to manage test execution. (Both manual and automated are supported.) It has a
standard Java project structure that supports the automated build process managed by Maven-2.
Work Items
Link Roles
Workflow
Change Request
Link Roles
Workflow
Issue
Link Roles
Workflow
Risk
Link Roles
Workflow
Software Requirement
Link Roles
Workflow
System Requirement
Link Roles
Workflow
Link Roles
Workflow
Task
Link Roles
Workflow
Test Case
Link Roles
Workflow
Link Roles
Workflow
Work Package
Link Roles
Workflow
A V-Model (Waterfall) based Project template that supports Requirement and Test Specification documents.
Start by filling in Requirement Specification documents. Then refine them in Test Case Specification
documents and specify the validation and verification procedures using the Validation and Verification
Plans. It supports a formal specification approval process.
Work Items
Task
Link Roles
Workflow
Change Request
Link Roles
Workflow
Issue
Link Roles
Workflow
Risk
Link Roles
Workflow
Software Requirement
Link Roles
Workflow
Link Roles
Workflow
System Requirement
Link Roles
Workflow
Link Roles
Workflow
A project in Polarion is a collection of artifacts and data residing on the system in a repository folder, which
is dedicated to managing some specific development activity throughout its life cycle.
• Create a new project from a Project Template: Available to all users who have permission to create
projects.
• Mark an existing repository folder as a Project: Available to project administrators only.
Polarion comes with several Project Templates. These range from a completely empty project with
just basic Work Item types and placeholder content, to projects preconfigured especially for some
type of development activity, for example, requirements management, Agile software development, test
management, or system engineering.
Related Topics
Tip
Not sure what template to use? You can learn about them, their default Work Item types and Link Roles
in the following links:
Project templates contain predefined key artifacts such as specification documents and reports, Work Item
types, workflow, and other predefined project configurations. The templates can provide a time-saving
head start for projects of the type for which they were designed.
The default templates may be suitable for many projects, but you can also customize them.
Tip
You can't create an empty Project Group, but you can create one automatically when moving
existing Projects or when defining the path of a new Project.
Procedure
Tip
The action is also available in the Open Project or Project Group dialog box.
If the action does not appear, it means you do not have permission to create new projects.
• Location: Enter a Group Name (optional) in the first Location field on the left and a Project
Name in the Location field on the right.
(The Location and ID fields may be prefilled to a default value if configured in the system
properties.)
Tip
If you want to reorganize existing Projects, you can create new Project Groups on the fly
while moving them.
• Tracker Prefix: Enter a value that is prefixed to the system-generated IDs of all new Work Items in
the project.
(Generally, you should limit the value to two to five characters that relate to the project name.)
Caution
Specify a unique value that is not used in any other project.
2. Enter an ID. (A unique identifier for the project. Acceptable characters are a-z, A-Z, 0-9, underscore,
dash, and period.)
As you type the ID string, your entry is suggested as the name for the project's folder in the repository
in the Location field.
(The Location and ID fields may be prefilled to a default value if configured in the system properties.)
Tip
If you want to reorganize existing Projects, you can create new Project Groups on the fly
while moving them.
• Enter a new Project Group in the Location field on the left and a Project Name in the
Location field on the right.
• Click the folder that you'd like to create the Project in.
4. Click .
The Select Project Group dialog box appears.
Caution
Once you click Next, your project's details can only be modified by an administrator.
The Project Group and Project creation begins. (This may take several minutes.)
The Creation page appears when creation is complete.
Note
If you create a project from a template with icon and color settings, it inherits these settings.
(Administrators or the user that created the project can always change them.)
9. Click Finish.
The Project appears in the Open Project or Project Group dialog box.
If a Project is removed, the settings for its Location are preserved in the access control file of the
internal Subversion repository. If you try to create another Project in that same location, Polarion warns
you and offers the possibility to overwrite the old settings. You should follow your administrator's policy on
such overwrites.
To create a new Project Group, specify its folder name in the target repository path when creating a
new project, or moving an existing project.
Tip
You can't create an empty Project Group, but you can create one automatically when moving an
existing Project or creating a new one.
Procedure
1. Click in the Navigation Header and select Open Project or Project Group.
Access projects
Users have read access to projects by default. However, administrators can restrict access to any project
and to some types of content within projects, such as Documents or Plans.
Related Topics
Your ability to open a project and read or change project content and artifacts depends on the user roles
assigned to your user account, and the permissions granted those roles by your Polarion administrators.
Procedure
1. Log on to Polarion.
2. Click the name of the current project or repository shown in the Navigation Header to display a
menu containing options for opening a project.
5. In the Open Project or Project Group dialog box, locate the project you want to access and click
the name to open it. If the project is part of a project group (green folder icon), you need to expand
the project group node to see the project.
Tip
Here are several tips about opening projects:
• If there are many projects in the system, you can select the My Projects tab to limit the list to only
those project for which you are assigned some role.
• You can navigate directly to any URL in your Polarion system by entering it in your browser's address
bar. You may find it useful to create bookmarks or Favorites in your browser for frequently visited URLs
such as projects.
• You can create Shortcuts in your Polarion system that quickly navigate you to any project or project
content.
• If you want to see dashboard and report data for a group of projects, select the desired Project Group
(green folder) in the steps above rather than an individual Project (blue folder).
Some Polarion systems are configured with multiple Polarion servers. On such systems, you might be
logged on to one server and then need to access a project hosted on a different server, requiring you to
switch servers.
Procedure
1. Click the name of the current project shown in the Navigation Header. A menu appears.
Documents belonging to a project can be found under the Documents and Pages topic in Navigation.
Procedure
1. Log on if you have not already done so, and open a project.
3. Expand the node for any space to see and browse its Documents and Pages in Navigation.
The items appear in alphabetical order regardless of type. If there are too many items to browse
easily in Navigation, click Index to open the space Index page, which displays a table of the project's
Documents and Pages.
Tip
If there are many Documents and Pages, you may find it quicker to use the Search feature to
locate the content you want.
Work Item is a general term applied to granular artifacts that need to be worked on or processed by
people through a workflow and lifecycle. Work Items most often represent things like requirements,
tasks, change requests, test cases, and defects/issues. However, it is possible to define Work Item types to
represent anything that you need to track and manage through a workflow-controlled process.
For quick access to a project's Work Items, click the Work Items topic in Navigation pane when the
project open.
The Work Items page enables you to query for Work Items, edit them, and perform other operations on
them. You can select any of several views that display sets of Work Items in different ways:
The names of the views describe the format or functionality of the information presented. The views
available in the menu when you select Work Items in Navigation depends on the product license you are
currently using. Not all licenses show all Work Items views.
• Tree: Displays a table of Work Items retrieved by the current query, plus any Work Items linked to
those items, in a tree structure.
• Road Map: Presents a table of Work Items selected by the current query. You can further filter the
selection according to Time Point.
• Matrix: Enables you to trace links between Work Items. You create two queries, one for Rows and
one for Columns of the matrix. With the query results you can specify the relationship you want to see in
the results, for example, dependency, duplication, or relativity.
• Time Sheet: Enables initial time reporting or redistribution of reported time for the set of Work
Items retrieved by the current query, usually for a specified period of time.
You can use queries and shortcuts to filter the list of Work Items retrieved in different pages displaying
Work Items.
• In Navigation, you can filter the Work Items table for a particular type of Work Item by clicking on
the one of the subtopics under the Work Items topic.
• You can use certain Shortcuts in Navigation to filter the list of Work Items in the Table and other views.
For example, the My Work Items shortcut retrieves only items assigned to you.
• You can further refine any set of retrieved items using a query. The parameters of the current query
are always shown visually in the Query Builder located in the toolbar of the Work Items page. You can
modify the current query to further filter the Work Items shown.
Tip
You can save the results of any query as a Shortcut. Click Save as Shortcut in the Navigation pane.
The saved Shortcut stores the current Work Items view, all query parts, table columns, and table sorting.
3. User guide
Home
Every project in the Polarion portal has a Home page. The default content is provided by the project
template. Home page content can be modified by users with the necessary permissions. The repository
also has a Home page, also modifiable by users who have permissions allowing them to change content in
that scope.
The Home topic of Navigation provides access to the Home page of either the current project, if you have a
project open, or the repository if you are working in that scope after opening the repository.
Every Polarion user has a personal home page and can customize the page to show the most useful
information. The page is not visible to other users. Users can also personalize Navigation to provide quick
access to the project content they need most often.
Tip
You can always access the repository Home page via the Polarion icon in Navigation.
Home pages are persistent LiveReport type Pages, and cannot be deleted like user-created Pages. If you
have permission to modify home pages in the scope (project or repository), you can edit a Home page.
The repository Home page, and every project home page, initially contain some default content. The
default content provides information about what the Page is and how to begin editing the content.
In the global, Repository scope, the repository Home page can be customized to provide essential
information for all users of the portal. This is typically company-wide information. For example, you might
add information that new employees or contractors need. The repository has its own space, and as with
projects, you can create more spaces and Pages in this scope and link to them in the repository Home
page.
On a project Home page, you and your team can provide information that is important to the people
accessing the project. You don't need to include everything on the Project Home page; you can create
other Pages, and then provide links to them in the project Home page.
To be able to edit the content of any Home page, you must have write permissions for the scope in which
you are working (project or Repository). If you find you cannot edit a Home page, contact the project or
portal administrator.
Procedure
1. Click Expand Tools at the top of the page to expose the page toolbar
2. On the page toolbar, click Edit. The page opens in the Page Designer.
3. Edit the page as you need.
Note
From version 2016-SR1, default pages such as Repository and space Home pages are created as
LiveReport type Pages. If these pages were created using a previous version and still have only
the default content, the format is switched when the system is updated. If these pages have been
customized, they remain as Classic Wiki pages and can only be switched manually to the LiveReport
format. For information on the conversion procedure, see Converting from Classic Wiki Format.
The default content of the personal Home page is merely a suggestion. You can change both the content
and the page layout to show whatever information you find useful for your work now, and you can update
the page any time.
When your user account is created, your personal Home page is also created. You can access it via the My
Polarion link in the Navigation panel.
Caution
Your administrators may have opted to specify a customized template as the default My Polarion page
for all users.
If they did, and you modify this page, it will be decoupled from the global template and will no longer be
updated when the template is.
(Click then Reset at the page to revert back to the global template.)
Tip
Don't confuse your personal Home page with your User Account page.
Your personal Home page, named My Polarion, is a persistent LiveReport type Page that cannot be
deleted like user-created Pages. Your My Polarion page is not public and only you or an administrator
can view and edit it.
When you access your personal Home page for the first time, a basic template page is displayed showing:
• An introductory paragraph.
• A region displaying your currently-planned Tasks and Defects, retrieved by query in a Table Block Widget
embedded in the Page.
• A region displaying Documents awaiting your signature (if any), retrieved by a custom script in a Script
Block Widget, and providing links to the Signatures view of the Documents.
• A region displaying Work Items awaiting your approval (if any), retrieved by query in another Table Block
Widget embedded in the Page.
• A list of Work Items assigned to you, with outgoing links marked as suspect and implemented in a Table
Block Widget.
• A column with:
◦ Links to some key pages which can be useful for you, including a link to your user account page
where you can change password or email address.
◦ The Activity Stream of the current project in which you are currently working.
Your personal Home page is a LiveReport type Page built with visually editable Widgets that you use
to build your home page. You have the full features of the LiveReport type Pages available to you. For
information, see Working with Pages.
From version 2016-SR1, new users' personal home pages (and other default pages such as Repository and
space Home pages) are created as LiveReport type Pages. This technology replaces the older Classic Wiki
technology for information and report pages.
LiveReport type Pages are easier for nontechnical users; thanks to construction using visually configurable
Widgets rather than mark-up language and code.
If you have an existing My Polarion (or other default) page created with a Polarion version prior to
2016-SR1, you can easily convert your existing page to use the newer and easier Pages technology.
Procedure
1. Log on to your Polarion portal, and in Navigation click My Polarion (or select any space's Home
node).
2. At the top of the page, click Expand Tools, and then click Edit.
If you see the Widgets sidebar on the right, your page is already using the newer Pages technology and
there is no need to convert. If you see the Wiki Syntax Help sidebar, your page is using the deprecated
Classic Wiki technology. Classic Wiki will be supported for some time to come, but conversion to the new
Pages technology is recommended. Please note that Classic Wiki content will not be migrated, and you will
need to customize the default content of the LiveReport page to suit your needs. The source of the original
Classic Wiki report will still be available to you for copy/paste.
Procedure
Your user account page is where you can access and edit your information in Polarion.
2. Click My Account.
Note
◦ Your can change your password if your Polarion administrators setup user credentials directly in
Polarion.
◦ If they setup user Single-sign on authentication via an external provider on authentication you will
not be able to change your password here.
• Edit your full name and initials, and provide descriptive information about yourself. This information
appears to other users.
• View or change your email address.
• Add, remove, or change an avatar image.
• Disable email notifications.
• Access your User Calendar. (See Configure your user calendar.)
• Access the Work Items you are currently watching (via the Watches button).
• Reset the user interface. The Reset UI Defaults button removes all your user interface customizations
and restores confirmation dialogs if you have previously chosen not to show them. The reset affects only
you.
• View your current Global and Project user roles, and modify them if you have the necessary
permissions.
• View and edit your time-splitting assignments, if you split your working hours among different projects.
This makes the calculation of the project and release plans more accurate.
Tip
Administrators can allow users to view the My Account pages of their peers.
In your user account page, you can specify an avatar image to display in Polarion.
The image is displayed with your activities in the Activity Stream, and you see it in the Navigation panel
when you are logged on.
A default avatar image is displayed in Polarion until you specify a different image. If you remove an image
you specified, Polarion reverts to this default image.
An uploaded image replaces the Polarion default avatar image, and takes precedence over any image on
gravatar.com that may be set on that site for the email address set in your Polarion user account.
Procedure
1. After logging on, click the Tool in the upper-left corner of Navigation, and then click My Account.
2. Click Upload avatar.
Note
Your avatar image should be square, and ideally 50 x 50 pixels. Larger square images are resized
to 50 x 50 pixels (maximum image file size is 50 kilobytes). Rectangular images are automatically
cropped or expanded to fit into a 50 x 50 space. The result may not be what you want, so cropping
the image yourself is recommended. Supported image formats are: .gif, .png, and .jpg/.jpeg.
3. In the Upload Avatar dialog box, click Browse, select the desired image file on your local system, and
click the Upload button.
Caution
Support for Gravatar images is deprecated and scheduled for removal.
Avatar images on gravatar.com are linked to email addresses. To use an avatar image from gravatar.com
in Polarion, make sure the email address used in your Polarion user account is set up in your gravatar.com
account, and that an appropriately sized image is linked to that address. When you first set up a new email
address on gravatar.com, it may take as much as 30 minutes before it appears in Polarion.
Note
Polarion administrators may optionally disable pulling avatar images from gravatar.com into a Polarion
installation. If you are sure your Polarion email address is set up in your gravatar.com account and you
don't see the avatar in Polarion, this is probably the reason. In that case, you need to upload an avatar
image to your Polarion user account page, as described in the previous section.
Personalize Navigation
In addition to customizing your personal My Polarion home page, you can personalize Navigation to
make it quick and easy to access the project content you most need to work with right now.
The Navigation Header at the top displays what artifact you are currently working in and the project that
it belongs to.
Tip
• Administrators can customize the Create button and the artifacts users can Quick Create from the
Navigation Header.
• Administrators, (or the user that created a project) can also select a custom project icon for the
Navigation Header.
• When hovering over the Smart Title of an item in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Polarion object link with its Title (or ID and Title) as the
link's label.
The Navigation panel on the left contains two sections of navigation links. The first section is for your
Favorites. Favorites are personal links to project content that are only accessible when you are working
in the project. (This is different from User Shortcuts, which are accessible from anywhere you may be
working in the portal.) Favorites enable you to create quick, easily-accessed links to any project content
you need to work with most frequently. If your needs change, you can remove Favorites and add new
ones to Navigation. For example, if you are working on a requirements specification Document, you
can create a Favorite that links you to it. If there are some Pages you need to refer to while working on
the specification, you can create Favorites for them as well. Then later, if you switch to working on a test
case specification, you can add a Favorite for that, optionally removing other Favorites if you no longer
need them frequently.
Initially, the Favorites section may be populated with default shortcuts preconfigured in the project
template on which your project is based. If you don't need these default shortcuts, you can easily remove
them. See Modify Favorites.
The second section contains the portal topics that are currently accessible to you. By default this section
is collapsed and shows only those topics currently "pinned". Pinned topics show when the topics list is
collapsed. The Documents and Pages topic and the Work Items topic are pinned by default.
You can further customize your Navigation panel by pinning some topics and unpinning others. Hover
your pointer above a topic and click the Pin icon. Keep in mind that the topics that appear in the expanded
list depend on several factors including the license you are using and the interface view configuration,
which controls what topics appear in the list when an interface view is active.
In the project where you want to create the new Favorite, navigate to the content you want to access with
it. If it is a specific Work Item, you must open the item itself.
If you just select it in a Work Item view ( Table, for example) the shortcut will lead to the view, not to
the item.
Tip
You can also add a project as a Favorite and easily access it from your Favorites list.
Procedure
1. In Navigation, click the star icon. The New Shortcut dialog box opens.
2. (Optional) Change the default Favorite name in the Name field.
3. Leave the default item Favorite selected in the Type field.
4. (Optional) Select a different icon from the icon library, and then click Add to create the new Favorite.
Modify Favorites
You can remove existing Favorites, edit their order, names, or icons and more, all within the Manage
Shortcuts dialog box.
To modify Favorites:
Note
You cannot remove the Home shortcut that leads to the project Home page.
Procedure
3. On the Favorites tab of the Manage Shortcuts dialog box, select a Favorite from the list of current
Favorite shortcuts.
4. You can modify the Favorite shortcut in the following ways:
• Click Remove to remove a selected Favorite.
• Click Up or Down to move a selected shortcut up or down the list.
• Click Cancel to cancel changes.
• Click Reset to revert to the default shortcuts to the default set.
• Click Save to save changes.
You cannot remove the Home shortcut. You can edit the name, change the icon, or shift its
position in the list.
What to do next
Tip
You can reset your user interface to the original state (the state when you logged on for the first time)
on your user account page. This restores display of confirmation dialogs if you turned it off.
Dashboard
The Dashboard topic of Navigation is useful for managers and other stakeholders who need to keep an
eye on the status of development, from single projects, to divisions or departments, on up through the
enterprise.
Caution
The Dashboard topic is deprecated and scheduled for removal.
The topic provides dashboards in several information scopes that roll up actual progress data maintained
in the repository as people begin and complete tasks. The data is presented in charts, graphs, and other
meaningful ways that help people understand the true status of development.
The information in the various dashboards and dashboard components can be as current as you need.
Updating the dashboards is generally done with a scheduled job on the server configured to run when
the extra system resources needed for the recalculations do not have any significant impact on users of
the Polarion portal. For example, the update job could be scheduled to run at night, and weekly, nightly,
or whatever interval provides enough currency for your needs. It is possible to update most dashboard
components explicitly to get up-to-the-minute information in real-time.
In the Repository or Project Group scope, the Dashboard topic provides several charts with key pieces
of information about the status of all projects being managed with Polarion (Repository scope), or in the
currently viewed project group.
Caution
The Dashboard topic is deprecated and scheduled for removal.
• Process Score: This table rolls up key information from the reports in the Quality topic, and provides
links to details in that topic. In the Repository scope, or a top-level project group, links to projects and
subgroups appear enabling drill-down to additional information. For an individual project group, links to
the projects in the group appear, again enabling drill-down to that level of detail.
• Top 5 Projects: A table shows the Maven-2 projects (up to five) having the highest level of code reuse,
and some basic statistics on the levels of reuse.
• Top 5 Packages: A table shows the most reused Java packages (up to five), and a count of the number
of times each package is reused.
Legacy charts
This page originally contained two charts that were rendered with Adobe Flash, which reached end-of-life
in 2020. In version 21 R1 these charts no longer work, and a discontinued notice appears in their places.
The list below describes these charts in case you want to replicate the functionality using Highcharts or
report page widgets.
• Work Items Trend: A chart that shows the trend of unresolved Work Items over time. If you see
sharp deviations in the curve, this might signal that something is happening that needs attention. For
example, if the trend is sharply up, there may be many new defects being reported. If sharply down,
some project(s) may be ahead of schedule and perhaps more features or testing can be planned.
• Test Coverage: For Maven projects, this chart shows the ratio of lines of code covered by tests versus
the total lines of code in all Projects or the currently viewed Project Group.
Project Dashboard
In the Project scope, the Dashboard topic provides information about the currently open project.
Caution
The Dashboard topic is deprecated and scheduled for removal.
• Several statistics:
◦ Build Frequency
◦ Build Success Ratio
◦ Test Success Ratio
◦ Test Coverage
◦ Traceability Work Items to Commits
◦ Traceability Commits to Work Items
• Facts and Figures: This section rolls up some useful metrics from various sources which can reveal even
more about what's happening with this project including the number of open Work Items according to
severity, recent changes, and most active developer.
Legacy charts
This page originally contained several charts that were rendered with Adobe Flash, which reached end-
of-life in 2020. In version 21 R1 these charts no longer work, and a discontinued notice appears in
their places. The list below describes these charts in case you want to replicate the functionality using
Highcharts or report page widgets.
• Work Item Trend: Shows the trend of unresolved Work Items over time. If you see sharp deviations in
the curve, this might signal that something is happening that needs attention. For example, if the trend
is sharply up, there may be many new defects being reported. If sharply down, some project(s) may be
ahead of schedule and perhaps more features or testing can be planned.
• Test Coverage: For Maven projects, shows the ratio of lines of code covered by tests versus the total
lines of code in the current Project.
• Quality Score Card: This table rolls up key information from the reports in the Quality topic, and
provides links to details in that topic. The information scope is the current project.
The Repository and Project Group Dashboards and Project Dashboard sections describe the default
composition of the Dashboard topic in a default installation. You should bear in mind, however, that the
topic is implemented as a Wiki page, and is modifiable by any user with appropriate permissions in the
information scope. The actual content you see in the topic on your system could be somewhat or even
significantly different from the default. The various components could be rearranged, or some could be
removed altogether.
Caution
The Dashboard topic is deprecated and scheduled for removal.
In a default installation, the system configuration contains scheduled jobs that recalculate the information
displayed in the dashboards. An administrator can review these in the Scheduler topic of the
Administration interface and optionally alter the default cron expressions that control the launching
of the jobs.
Some components of the dashboards contain an Update link that invokes an immediate recalculation of
the information displayed in the component to provide up-to-the-minute information:
Warning
Recalculating dashboard information places some extra load on the server's resources. While Polarion is
optimized to update as efficiently as possible, if the scope of the information is very large and the server
has a lot of traffic, the update could take some time, and performance could slow down somewhat for all
users.
Plans
About Plans
The Plans feature enables teams to easily plan their work into releases.
Releases can be internal or external. For example, they might be iterations or milestones which are internal
to the development organization, and releases that are provided to customers and users.
Plans are created only in the project scope. They are often hierarchical. For example, a Plan for a release
named Version 1.1 might have several child Plans for iterations such as i21, i22, and i23. Teams can use
any desired naming convention for their Plans.
Plan basics
The Plans topic in Navigation is the entry point to view and manage your release plans. Plans allow you
to estimate work time, progress against each Plan, and can include multiple projects under a single Plan.
For each Plan, a team member or manager specifies the existing Work Items the team should complete
between the Plan's start and end (due) dates. Estimated Work Items contain a value in the Initial Estimate
field that indicates how long it takes to complete the item. The Plan aggregates and displays the total time
of all initial estimates. The teams and managers then easily compare the estimated total time with the
team's known capacity. For example, suppose the aggregated Initial Estimate for all the Work Items added
to a Plan is 48 days and 6 hours (48d, 6h), and the period of the plan is 45 days (45d). Before work even
begins, the team and managers can clearly see that the plan is overly ambitious and needs to be adjusted.
As work goes forward, charts in the Plan reflect the team's actual progress. Stakeholders clearly see at all
times how much work is complete, and how much remains to be completed in terms of person days/hours.
Teams and management are never left guessing about the probability of the Plan being completed by the
planned Due Date. If progress is not what they originally expected, they can make intelligent decisions
about adjusting the Plan, for example, removing some items from the Plan, or pushing the End Date
forward.
By default, a Plan includes Work Items from one project. However, Plans can span multiple projects. For
example, there might be separate projects for different components, all of which have the same release
cycle. Therefore, Plans for iterations and/or releases need to include Work Items from all relevant projects.
These projects can be specified in the Plan Properties.
Browse Plans
The Plans topic in Navigation shows the parent-child hierarchy of Plans in the current project. You can
navigate directly to any Plan by clicking on any top-level Plan, or expanding it and an clicking on the node
of any child Plan. You can also use the Search field in Navigation to search for a specific Plan.
The Plans page shows a tree table of existing Plans in the current project. The Name column shows the
hierarchy of the Plans.
You can filter the table for a Plan name using the Visual Query Builder in the page toolbar. When the
filter finds a Plan, any parent Plans are also shown. You can also filter by the Plan properties listed in
the FAVORITES column, and/or the Plan fields listed in the ALL column of the Visual Query Builder. The
instance of the Visual Query Builder on this page contains a limited set of query elements and element
value options relevant for Plans.
When a Plan is selected in the upper pane of the table, the Plan details appear in the lower pane.
Each user can customize the Plan page tree table columns via the Customize Table item on the drop-down
menu of the page toolbar (at the far right side) or by right-clicking the table header. The default visible
columns are:
• Name
• Status
• Progress
• Due Date
Tip
Calculated fields in Burn-up and Burn-down charts can only be calculated from direct children. Multi-
level calculation is not supported. Also, the relation of calculated fields in these charts cannot be based
on other calculated fields.
When customizing the Work Items table, it is possible to use the Planned In field as one of the sort
criteria.
Review a Plan
A Plan is a special type of page built with functionality that reads and processes data from the Work Items
that are added to the Plan.
This information is formatted in various ways in the Plan page to reflect the actual status and progress of
the planned Work Items in aggregate, and the Plan itself. The information presented differs according to
whether the Plan is for a Release or an Iteration. An Iteration Plan is more detailed, while a Release Plan
is broader in scope, rolling up information from all child Plans in its hierarchy.
You can review a Plan by selecting its node in Navigation under Plans, or in the tree table of Plans
displayed when you click the Plans node in Navigation.
Tip
When hovering over the Smart Title of a Plan in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Plan link with its Title as the link's label.
To review a Release Plan, examine the Release Plan's four main sections:
• Plan Status: Shows at a glance the status of the Plan (Open, In Progress, Done), the Start and Due dates,
and the amount of work done, still to do, and what the ideal progress should be at the time of the most
recent data update. (Usually when the page was loaded in the browser).
• Items Overview: Shows a table reflecting a count of planned items currently in each of the project's
Work Item statuses, for example, how many items are Open, Reopened, or Done.
• Child Plans: Shows a table of children of the current plan, if any, with a bar chart reflecting the current
progress of each child Plan. New Plan enables you to create a new Plan in the current project.
• Unresolved Planned Items: Shows a table of all currently unresolved Work Items that are part of the
current Plan. The table columns present useful statistics about each unresolved item.
The page section located in the right-hand column of the page provides a button set allowing any user
with the required permissions to change the Status of the current Plan. Another button, Open in Table,
is for invoking a special planning mode in which Work Items are located and selected for inclusion in the
current Plan.
You can review an Iteration Plan by viewing the major elements on the page of Plan iteration:
• Progress bar chart: Compare the actual progress of the team on the current plan (green) against the
calculated ideal progress.
• Plan Board: View a tabular listing of all Work Items of all types that are planned for processing during the
running of the current plan.
• Burn-down chart
• Burn-up chart
You can also view other elements including links to the following:
• Work Item Prioritization feature (to set priority for just the items in the current Plan).
• New browser tab in which you can browse just the items in the current Plan.
There is also a button set for setting the status of the current plan (Open, In Progress, Done).
You can only create Plans in a project; the global Repository scope is not supported.
Tip
Administrators can configure Quick Create so users can create a Plan right from the Navigation
Header.
Procedure
1. Open the project in which you want to create the new Plan.
5. After specifying a Plan type in the next dialog box, specify a name for the new Plan, and the parent
Plan, if any. (You can choose a Parent Plan from a list of open Plans.)
After creating a new Plan, you may want to modify some properties settings. Once the properties are set,
you the add Work Items to the Plan. Once you add Work Items, you may want to prioritize them.
When hovering over the Smart Title of a Plan in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Plan link with its Title as the link's label.
Plan properties
After a Plan is created, any user with permissions to modify the Plan can edit the Plan's properties.
Generally, Plan properties should be reviewed and set before Work Items are added to the Plan, and before
the team begins work on it. This is especially important if the Plan spans multiple projects.
1. Click the Properties button on the Plan detail pane toolbar (or Plan page toolbar if you are not
viewing the Plan in the table).
2. Click the Edit button to put the Plan Properties form into edit mode. Note that this may not always be
necessary, as many of the property fields can be edited in-place. Such fields provide visual feedback
when you hover over them.
Basic properties
• Start Date: The date planned for the team to start working on the Plan.
The Burn-down and Burn-up charts do not render any information until the Start Date property is set. In
addition, you must set other properties, add Work Items to the Plan, and start the Plan progress.
• Due Date: The data planned for the team to finish working on the Plan.
The Burn-down and Burn-up charts do not render any information until the Due Date property is set. In
addition, you must set other properties, add Work Items to the Plan, and start the Plan progress.
• Status: The current status of the Plan.
Default statuses are Open, In Progress, and Done. Status values can be customized in the Project
Administration.
• Capacity: The capacity of the team during the period beginning on Start Date and ending on Due Date.
The Capacity value can be hours or Scrum story points. The value is an important property to specify,
and specify accurately. Polarion calculates the progress statistics of the Plan by comparing the Capacity
value against the actual progress on processing the Plan's Work Items. (The Initial Estimate field of Work
Items reflects the capacity needed to process each item.)
• Started On: The date the team actually began working on the Plan.
It is important to set this field in order for the Plan to accurately report actual progress compared to
planned progress. The value is set automatically when Plan status changes to In Progress.
• Finished On: The date the team actually finished working on the Plan.
It is important to set this field in order for the Plan to accurately report how the plan actually progressed
compared to how it was planned to progress. The value is set automatically when Plan status changes to
Done.
• Parent: The ID of the Plan that is the immediate parent of the current Plan, if any. This property can be
left empty if the current plan is a top-level Plan in a hierarchy of Plans, that is, it is not a child of some
other Plan. The parent is usually specified when the Plan is created. However, if the parent was created
later, or the structure of Plans has evolved, you may need to set it here.
If you are not sure about the ID value, open the parent Plan and invoke the Open in Table action. The ID
is shown under the Plan title in the Planning sidebar.
You can set some properties in the Configuration of the Plan properties that control Plan content and
calculations. You can set the following configuration properties:
• Project Span: By default, a Plan is for the single project that its contained in and only Work Items within
that project can be added to it. Project Span adds Work Items to the Plan for multiple projects.
Specify the projects to include in this field. Include the Plan's own project if it also contains Work Items
to be added to the Plan. When a planner adds Work Items to the Plan, it is possible to select Work Items
from all projects specified here. Planners are able to access the Plan and add Work Items from any of the
projects specified, as well as the Plan's own project.
• Allowed Types: Restricts the type(s) of Work Items that can be added to a Plan. The list is dynamically
populated with all types defined in the projects specified in Project Span (or the current project if Project
Span is empty). By default, any of these types can be added to the Plan. You can restrict this to one or
more types.
For example, if the Plan is for a bug-fixing iteration, this property could be set to the Issue type, which
prevents the Plan from being populated with any other Work Item type besides Issues. If some Task
items are processed in the same iteration, that type can also be specified along with Issue. Planners can
then populate the Plan with only these types. They could not, for example, add Change Request items to
it.
• Prioritization Field: Specifies which field should be used to store priority values for Work Items in the
Plan when the items are prioritized.
By default, the standard Priority field of Work Items is used for prioritization. However, it is possible to
define one or more custom fields in the project configuration, which can be used to store priority values
for different kinds of prioritization. For example, there could be custom fields like Business Priority and
Development Priority, with the latter created for use with Plans. For more information, see Prioritizing
Work Items, and Prioritizing on a Custom Field.
• Calculation Type: Specifies the calculation Polarion uses to calculate and report the Plan's
progress. The default is Time Based, meaning that values for Remaining Estimate and Time
Spent are used to calculate Plan progress. By default, Remaining Estimate is calculated
on items that have Resolution set, but still have a Remaining Estimate value greater
than zero. If this is not the preferred behavior, an administrator can set the system
property com.polarion.plans.calculateResolvedRemainingEstimate to false so that the
Remaining Estimate value of resolved Work Items is not calculated.
Tip
The best practice is to clear Remaining Estimate when the terminal state of workflow is reached.
If Time Spent and Remaining Estimate are not filled for items planned to a time-based Plan, it behaves
like a custom field-based Plan, and the "burn when done" principle is followed using either Initial
Estimate (if filled) or the default estimate value as the Work To Do value of the Plan.
The other option is Custom Field Based. This means that a custom field is used to represent an estimate
of work. Work done is calculated as the sum of such a custom field for all the items that are resolved.
When this option is selected in the menu, the Estimation Field property becomes visible, and you can
select from a list of currently configured float type Work Item custom fields (the required type for this
property).
How the Agile fields are calculated:
◦ Ideal progress:
The amount of work that needs to be done that day to be "on time".
(A direct line that connects all remaining work at the beginning with 0 work remaining at the end.)
How it's calculated:
(# planned days passed)/(total # planned days)*total work
◦ Real progress:
How much work is actually done on that day.
(You can compare the Real and Ideal lines to determine how far ahead or behind schedule you are.)
How it's calculated:
time spent / (time spent + remaining estimate)
◦ Relative progress:
How much work was "burned" on each working day.
◦ Total work:
All work planned for the Plan.
How it's calculated:
The sum of (remaining estimate + time spent) or Story Points.
◦ To do:
The sum of the remaining estimates of all planned items, or the sum of Story Points on unresolved
items.
◦ Done:
The sum of the Time Spent on all planned items. (Sometimes days spent before the plan was started
are subtracted.)
Or;
The sum of Story Points on resolved items.
• Default Estimate: Specify a value to use for Work Items' Initial Estimate field. Use as the default for
any Work Items in the Plan that have no value set for their Initial Estimate field.
• Previous Time Spent: Stores the sum of the Time Spend field for a Plan that contains Work Items
which has some time already spent. That is, the items contain a value in their Time Spend field. This
property is updated automatically by the system and you should not normally need to edit it. You can
find detail about the calculation in Previous Time Spent Property.
The Plan properties page also provides a field for a Plan description, and a section where any custom fields
for the Plan, configured in Administration, can be edited.
The Actions menu in the Plan detail pane provides several functions you may need:
• Open in Table: Opens the selected Plan in the Table view, in a new browser tab. It also opens the
Planning sidebar. You use the Planning sidebar to add the Work Items the team plans to process during
the Plan time period to the project Plan.
• Prioritize Plan:
Opens those items in the Table view along with the Prioritization sidebar. This enables the Work
Items to be prioritized, after work items are added to the Plan. For more information on prioritizing Work
Items, see Prioritizing Work Items.
• Customize Plan Report: (ALM) Opens the underlying report Page of the Plan, enabling you to
modify the report layout, modify existing Widgets' parameters, and add other Widgets to provide the
functionality and information needed by the team.
If the Plan's report Page is shared from a Plan Template, you are offered the option to customize the
report Page of the current Plan, or the report Page of the Plan Template. (You must have the necessary
permissions in order to modify the template. The option is disabled if you don't.) After choosing an
option, the report Page opens in the Page Editor. Modifying the Plan Template report overwrites the
existing report, and all new Plans created from the Plan Template will have the changed report Page.
If the report Page is not shared from a Plan Template, no choice is presented, and the report Page of the
current Plan opens in the Page Editor ready for editing. (See also Working With Pages.)
• Delete: (ALM) Invoke this action to delete the currently selected Plan. If the Plan is the parent of other
Plans, the child plans are not deleted, and the name of the deleted parent Plan remains in their Parent
property. No Work Items are deleted from the repository, only the Plan object.
Note
The Actions menu also has actions to export the Plan page to PDF, or to print it.
When work on a Plan actually begins, be sure to set the Plan status to In Progress, or use the graphical In
Progress button on the Plan page. This sets the Started On property in the Plan properties to the current
date.
When all work on a Plan is completed, set the Plan status to Done, or use the graphical Done on the Plan
page. This sets the Finished On property in the Plan properties to the current date.
Note
While the ideal scenario is for the Started On date to be the same date as Start Date, and Finished
On the same as Due Date, this may not always reflect how the Plan actually went. Work on the Plan
might actually finish before or after the Due Date, for example. Reporting these dates accurately helps
managers and team leaders to understand, over time, their realistic capacity and to better estimate what
they can expect to deliver.
As with other artifacts, Polarion automatically maintains a change history for Plans.
This history is accessible from the History button located on the toolbar of each Plan. Clicking this icon
changes the page to show a listing of all revisions that currently exist in the repository. From there, you
can view a specific revision, or compare any two revisions. The Plans topic is included when a project
Baseline is created. When browsing a Baseline, you can browse Plans in the state they were at the time the
Baseline was created.
You can view the current Plan in the state it was at some point in the past. While viewing the history, click
the View a Revision button. On the next screen, specify the revision you want to view. You can use either
of two picker icons to pick a revision date, or a Project Baseline. Then click the Show button to view the
specified revision of the Plan. Note the following:
• If you know the revision number, you can type it directly in the field.
• If you use the Date picker (calendar) and pick a date in the future, the last existing revision is shown.
• If you use the Baseline picker, the list shows only Project Baselines in which the Plan existed. If the list is
empty, the Plan did not exist when any Project Baselines were created for the project.
Tip
When you view a completed (finished) Plan, the page normally displays a link that leads to the Baseline
that contains the historical revision of the Plan, in which the date in the Finished On field was set. If the
Finished On date is changed manually in Plan properties, the link leads to the Plan revision when that
date was updated. (If the history link is missing, someone has customized the Plan page and excluded
it.)
When viewing a Plan's history, you can compare any two revisions. Only changes to Work Items in the plan
are compared and not changes to Plan properties. This means the comparison shows Work Items added to
and removed from the Plan, and Work Item updates. Note that changes to Plan Properties are shown only
on the history page, not in revision comparisons.
You can create report Pages in your project to deliver up-to-date information about Plans to the team and
stakeholders.
Plans in projects based on one of the default project templates always include a preconfigured report Page
for the Plan. You can customize this default report Page, and/or create additional report Pages for any Plan.
The Pages feature includes several Widgets for retrieving and rendering information about a Plan, and
providing Plan-specific user actions. You can find them on the Plans tab of the Widgets sidebar in
the Page Editor.
• Plan Label: Renders a label of a specific Plan, showing its due date and type via a colored icon. For each
Plan, all its parents are shown to the highest level, as well as direct children. Finished Plans are shown in
strike-through font. It is also possible to create new child Plans via the + button.
• Work Items Board: Renders a Work Items Board (sometimes called Scrum Board) for a specific Plan.
It shows all the planned Work Items and their children in individual stages of development (grouped
if the statuses are similar). By default it shows all child items that are linked with any role with a
parent-child-role attribute. Users can select for which statuses the items are displayed compacted, to
minimize the space used.
• Plan Progress: Renders a progress bar that visually shows how much work from the specified Plan is
already done, how much remains, and what should be the ideal progress today to finish the entire Plan
on time.
• Plan Burn-Down: Renders a burn-down chart for a specific Plan, with customizable time scale and
labels.
• Plan Burn-Up: Renders a burn-up chart for a specific Plan, with customizable time scale and labels.
• Plan Activity Stream: Renders an Activity Stream showing activity limited to the Work Items planned in
a specific Plan.
• Plan Status Button: Renders a graphical button set that enables a user to set the status of a specific Plan
(Open, In-progress, Done). For a terminal status, the Finished On date of the Plan is shown.
• Open Plan in Table: Renders a graphical button that enables a user to open a specific Plan in the Table
view of Work Items. The table is limited to the Work Items currently planned in the specified Plan.
Note
You can optionally create Plan-related reports using Classic Wiki pages. Syntax details and usage
examples for Plan-related macros are provided in the Plans section of the embedded Wiki Syntax Help,
accessible from the Wiki Mark-up Editor when editing Classic Wiki pages. Advanced users can consult
the API documentation (Javadoc) for details on how to display various Plan statistics on Plan pages or in
charts.
Alternatively, if you have an existing Plan or Plan Template with the Plan report implemented as a Classic
Wiki page, the action Switch to LiveReport Page appears in the Actions menu on the Plan (or Plan
Template) page. The source of the existing Classic Wiki page is appended as the last region in the new
LiveReport Page. You can refer to it when customizing the new report Page, and delete the region when
finished building the new Page. For more information, see Build Reports.
Planning sidebar
This sidebar panel is available when viewing/editing a Plan in Table view, and when editing a Document.
The Planning sidebar is opened automatically by the Open in Table action.
( Actions menu, or Open in Table widget in a Plan. Cannot be invoked from a Document.)
Tip
The Planning sidebar can also be accessed by clicking the Planned In field in the Work Item table.
The Planning sidebar enables you to load any open Plan in the table, or open its page. This can be useful
when you are planning Work Items for a release or iteration. You can easily check any plan to see what
Work Items have been added to it and what the workload is like, and to add or remove Work Items in
different Plans until you have a release plan and any iteration sub-plans populated as you think best for
successful a execution.
Refer to the following figure when browsing the next sections in this topic.
Selection in Open Plans. (Click to open this Plan from a different project.
Plan.)
Add or Remove item(s) selected in the table Save changes to all modified Plans.
from the Plan selected in Open Plans.
Current selection in Open Plans. (Click icon to Cancel changes to all modified Plans.
load Plan in Table.)
The first element in the sidebar is the title of the Plan currently selected in the Open Plans list. The title
is a hyperlink that will open the respective Plan in the Plans topic of the project. The ID of the Plan is also
shown. This can be useful for developers needing to find the ID to cite it in a macro in a custom report
page, or in an API call.
After the Plan title and ID, the Planning sidebar shows several statistics about the Plan currently selected in
Open Plans.
• Items: a count of the number of Work Items currently planned for processing in the selected Plan.
• Planned: the amount of work estimated for all Work Items in the selected Plan. The metric may be time,
or something else defined in an estimation field, depending on the configuration in the Plan properties.
• Unplanned: Reports the Capacity (defined in plan properties) minus planned work. Planned work is the
sum of all work already done and still to be done in the Plan.
These buttons can be used to add Work Items currently listed in the Table to the Plan currently selected
in the Planning sidebar. Keep in mind that the Plan currently loaded in the Table may not be the Plan
currently selected in the sidebar. Observe the Query Builder in the table to see if the Planned In query
element is present. If so, then the Work Items in the table are already added to the Plan specified in the
query. Normally, you should not add items from that Plan to some other Plan selected in the sidebar,
without first removing it from the queried Plan.
Assuming the query in the table is not fetching items that are already planned, you can add items from the
table to any open Plan by first selecting it in the Open Plans tree in the sidebar. Select one or more items
in the Table, and click the Add button. Alternatively, you can drag items from the Table to the Planning
Sidebar to add them to the currently selected Plan.
If the Plan loaded in the Table is the same as the Plan selected in the sidebar, you can select items in that
Plan for removal from it. Select the items to remove, and click the Remove button in the sidebar.
Remember that no Plan is actually updated with changes made in the Planning sidebar until the changes
are saved via the Save button. The button shows a count of Plans that have changes pending.
This section of the Planning sidebar is a scrollable list of currently open Plans in the current project. If any
Plan has child Plans, its node can be expanded or collapsed to show or hide the child Plans. If a plan is one
in a different project that has been included in the currently-viewed plan, the ID of that project appears in
parentheses after the Plan name.
Selecting a Plan in the tree shows its current work statistics. It is important to note that selecting a Plan
here does not load its Work Items in the Table. If you want to do that, hover over the Plan when it is
selected in the tree, and click on the icon that appears (Show Plan Work Items in Table).
You can use the Planning sidebar to jump around among different Plans and make changes (add Work
Items, remove Work Items). However, no Plan is actually updated until you click this button. The button
label displays a count of how many Plans have changes pending.
Clicking this link cancels all unsaved changes to all Plans, and closes the Planning sidebar. You can reopen
the sidebar from the Sidebar drop-down menu, located to the right of the Query Builder in Table view.
The Previous Time Spent property of Plans stores the sum of all non-null values present in the Time
Spent field of Work Items that have been added to the Plan.
It affects statistics calculations of Plans in progress if these are calculated on the basis of time. In this type
of Plan:
• When the Plan is not started yet, time spent is not reflected in the planned work. For example, if a user
story is added to an Iteration Plan that is in progress from last iteration (for example, 1d remaining, 2d
spent), only 1d is included in the Plan's total work, not 3d.
• When the Plan status changed to In Progress, meaning that the Plan is started, the aggregated time
spent value from all of the Plan's Work Items is written to the Previous Time Spent property. In the
example above, the 2d time spent value would be written.
Once the iteration has started, the total planned work effort is calculated as: To Do + Current Time Spent -
Previous Time Spent. If, during the iteration, a user reports an additional 6h done (so time spent = 2d 6h),
but remaining To Do is 6h, then the planned work on Burn-up is Day 1: 1d, Day 2: 12h (22h + 6h - 16h =
12h). Users see the plan has been increased by 4h.
Plans report various statistics that reveal to the team and managers the current state and overall progress
of the Plan. Most statistics are self-explanatory.
One statistic, named Ideal Progress needs some background in order to correctly understand what it
means.
The calculation formula for this statistic can be expressed as follows: Ideal Progress = (D1 / D2) * T
where...
Working days are per the Working Calender in the project configuration. Keep in mind that projects use the
Global Working Calendar configuration by default. If working days for the project differ, be sure to have
an administrator create a project-scope Working Calendar so that Ideal Progress is calculated correctly for
Plans in the project.
Plan macros
This topic lists the macros you can use in Classic Wiki pages (including the underling wiki page of Plans)
to report information about Plans. Syntax details and usage examples for these macros can be found in the
Plans section of the embedded Wiki Syntax Help.
Warning
The information in this section is now considered deprecated. It is still provided here for those who
have legacy Plan reports implemented as Classic Wiki pages. New Plan reports should be created as
LiveReport type Pages using the set of Plan-related Widgets. For more information see: Creating Plan
Reports.
The {workitems-board} macro renders an easy to understand summary of the Work Items in any Plan.
The Work Items Board can be configured with columns summarizing the Plan's Work Items in different
states, such as To Do, In Progress, Verified, and Done. Note that only following Work Items are shown on
the Work Item board:
See Work Items Board to add a drag and drop board to LiveReports, Info Pages and Plans.
• Parent items: Work Items added to the Plan specified in the plan parameter.
• Child items: Work Items with a link to those added to the specified Plan, and where such added Work
Items have the parent link role to them (by default, if no roles parameter is specified)
• Work Items with status defined in the columns parameter of the macro.
The {plan-burndown} macro renders a Scrum-style "burn-down" chart of a Plan's Work Items. The
{plan-burnup} macro, renders a "burn-up" chart of the Work Items.
In order for the Burn-down or Burn-up charts to show correct data, it is necessary to:
• Specify the Plan's Start Date and Due Date in the Plan properties.
• Add Work Items to the Plan (see: Planning Work Items)
• Be sure all Work Items in the Plan are estimated (i.e. the Initial Estimate field should be filled in for
every Work Item).
• Start the Plan on the same date specified in the Plan's Start Date property. That is, the value in the
Started On property should match that in the Start Date property.
After the Plan is started, avoid changing Start Date or Started On date to keep progress reporting
accurate. You may, however, add Work Items to a Plan after it has started, and the total work and ideal
progress statistics will be updated accordingly. However, adding Work Items after Plan start is not a
recommended best practice.
The {plan-open-in-table} macro renders the Open in Table button in the Plan page, which, when
clicked by a user, opens a new browser tab and loads the Work Items Table filtered to show the Work
Items currently in the Plan (by means of the Planned In visual query element.)
Plans – {plans}
The {plans} macro displays open Plans that are child Plans of the one specified in the macro's plan
parameter, and also Plans set by the query defined in the macro.
The {plan-status-button} can be used in Plans only. It will not work in Wiki pages. It renders a button that
shows current status of the Plan and enables the user to set a different status. If status is set to "Done", the
Plans Finished On property is set to the current date/time.
The {plan-label} macro shows the name and hierarchical structure of the Plan specified in the plan
parameter of the macro. Users can click on the displayed parent or child Plans to jump directly to those
Plans. The macro also provides an action for creating a new child Plan of the specified Plan.
The {plan-progress} macro displays the progress bar of the Plan specified in the plan parameter of
the macro.
The macro starts showing the Done value only after the Plan is started. Otherwise, it shows only the ideal
progress metric.
Decide which Work Items the team will process and complete during Plan period, and add them to the
Plan.
Procedure
2. Click Open In Table to open the Plan in the table view, together with the Planning
Sidebar panel.
Tip
You can also click the Planned In field in the Work Item table to access the Planning Sidebar.
3. Run one or more queries to locate the Work Items to be added to the Plan.
4. Use control and widgets in the Work Items Table and the Planning sidebar to plan Work Items by
adding them to the Plan.
I you have an open Plan and are ready to plan Work Items into it, open the plan in Table view. There,
you can run queries to locate the Work Items for the Plan, select them, and add them to the Plan. You can
also modify the Plan, removing previously planned items.
Procedure
You can open a current plan in the table by one of the following:
• On the Plan page, click Open in Table.
• On the Plan toolbar, click and from the list, select Open in Table.
A new browser tab opens, loading the Table view, creating and running a visual query element to
retrieve the Work Items for the Plan, and opening the Planning sidebar. You are now ready to begin
planning Work Items into the Plan.
If no Work Items have been planned yet, the Table is empty. This is because of the visual query that is
specified to retrieve the items in this Plan. You need to remove the query element and build a new query
to retrieve all or some of the items you want to add to the Plan. (For information on Work Item queries,
see Search Work Items.) You may find it easier to build several simple queries rather than a single complex
one. Each query should show some Work Items in the table, and at least some of those should be items
you want in the Plan. (If none of them are, you need to revise your query.)
You can use the visual query element Planned In to retrieve the Work Items that have been added (or
NOT added) to one specific plan and aggregate the view with items from more than one Plan. (See Query
Builder for more information on graphical queries.)
Once the table contains items you want to be processed during the Plan period, you can easily add them
to the plan:
Procedure
1. Select one or more items in the table by checking the box on the respective row(s).
2. You can add the item to the Plan in several ways:
• On the Planning Sidebar, click Add. A count of items selected for adding appears
• Drag a single or multiple selected items from the table to the Planning Sidebar.
• Click the icon on the table row of an item you want to add to the Plan.
Tip
• When items are added to the Plan, the plan Statistics are updated immediately in the sidebar panel.
If you added some items by mistake, or you change your mind after seeing the statistics, you can
remove one or more items from the Plan by selecting them in the table and clicking the Remove
button.
• You can save the changes to the Plan any time during the planning process. Be sure to save changes
when you are finished adding items to the plan.
• You can review the Work Items in any Plan by selecting the Plan in the Planning sidebar and clicking
the icon.
• You can return from the Table to the Plan by clicking on the Plan name in the Planning sidebar.
• You can navigate a tree of open Plans, and jump into any listed Plan from the Open Plans section of
the Planning sidebar.
• When viewing an individual Work Item in the Work Item detail form, the Planned in field lists all Plans
that include the item. The field is editable. You can remove a Plan from the field, which removes the
item from the removed Plan. You can add another Plan to the field, which adds the current item to the
selected Plan.
• You can also add a Planned In column to the Work Items Table. The column displays all Plans that
include the selected Work Item.
Click on a listed Plan to open the Planning Sidebar. (Because it is multivalued, the table cannot be
sorted based on this column.)
You can also add Work Items to a Plan from the Document Editor. You need to manually open the
Planning Sidebar and select a Plan. Then click the icon in the Document margin beside any Work Item
to add it to the Plan.
Note
The type of Work Item must be a type that is allowed in the Plan by its properties. For example, if
the Document contains Requirement items, but the Plan properties include only Change Request and
Issue type items, you are not be able to add Requirement items to the Plan. You first need to modify the
Plan properties to include the Requirement type.
Setting priority values for Work Items in your Plan is optional. Assuming that you want to do it, you can use
the same basic procedure as for prioritizing Work Items in general.
Review Prioritize Work Items. Several issues that are specific to prioritizing the Work Items of a Plan
follow:
By default, Work Items are prioritized using the standard Priority field of Work Items. You should decide
whether this meets your needs for prioritizing Work Items in a Plan. For example, you may find that the
standard field is fine for setting priority for a Release Plan, but your developers need to set their own
priority for an Iteration Plan. In this case, you might need to have your project administrator create a
custom field for relevant Work Item types, with a name such as "Iteration Priority". (The field must be of
type float.) This custom field should then be specified in the Prioritization Field property of the Iteration
Plan(s).
It is best if you have already added all the Work Items to the Plan that should be resolved during the Plan
period. You can reprioritize the items any time, however. Let's assume you have the Work Items already in
the Plan and you are ready to prioritize them.
On the Plan toolbar, click Actions Prioritize Plan. The Plan opens in the Work Items Table view,
with the Prioritization sidebar open. All the Work Items currently added to the Plan are listed. If the plan
spans multiple projects, the list includes items from the projects specified in the Plan Properties. The table
of items is sorted top to bottom on the current value of the field specified as the Prioritization Field (see
Store Priority Data). You will be changing this value for some or all of the Work Items during prioritization.
With only the Plan's Work Items in the table, you can change their priority by drag-drop repositioning in the
table, or any of the other ways described in Prioritize Work Items. You can optionally modify the visual
query as needed to limit the items in the table to one type, for example, Issues.
Work Items
The Work Items topic in Navigation provides access to the integrated bug (issue) tracker, one of the most
widely and frequently used Polarion tools.
A Work Item is the Polarion term for an artifact of the development process that is waiting to be
implemented, is in progress, or has been implemented.
You can review Work Items in any information scope (all items in the system, a group of projects, or one
project). You access Work Items by first opening the scope you want to work with (for example open
a project), and then selecting the Work Items topic in the Navigation pane. The Work Items topic
contains the integrated Tracker feature. You can track any kind of artifact by defining a Work Item type for
it.
Work Item types can be created to represent anything that you need to track and manage through a
workflow-controlled process.
• Requirement
• Task
• Change Request
• Defect
• Test Case
Work Item types are generally defined in the underlying Project Template from which a project is created.
In any project created from a Project Template, the default Work Item types can be customized by an
administrator, modifying properties of existing types and/or new defining new types.
Each Work Item has a number of default data fields which are used to describe and categorize the item,
assign it to someone, and incorporate it into project planning and tracking, set its status, and so forth.
Administrators can define Custom Fields for any Work Item type, enabling tracking of and querying on
any kind of information needed by a project.
Caution
There is a special Work Item type named Heading that can only exist in the context of LiveDoc
Documents. A Work Item of this type is created whenever you add any level of heading to a Document.
This makes it possible to query for headings contained in Documents.
You should not ask administrators to customize the Heading type with Custom Fields, modified
workflow, etc. Although the system does not block such operations, customization of this type can
prevent some Polarion functionality for working correctly.
Table view
The contents of the table varies according to the current query, shown in the Query Builder. By default,
the table is sorted by Work Item ID in ascending order. You can sort the table on any column by
clicking the column header. A Polarion administrator can customize the names and other properties of the
columns, and add or remove columns. (See Configure the Work Items Table.)
When you select a Work Item in the Table view, the panes are tiled horizontally. The top pane shows
a table of Work Items retrieved by the current query, and the bottom pane displays a multi-section form
providing access to the various data fields the item(s) currently selected in the table. Some of the key Work
Item fields are editable in place, so it is not necessary to load the entire Work Item in Edit mode in order to
make some common edits (setting a new Status, for example).
Tip
• You can also edit some fields directly in the tree.
• Hold CTRL and left click to select multiple Work Items.
• Hold Shift and left click to select a range or Work Items.
By default, the IDs of Work Items in this view (and wherever they appear throughout the entire system)
are rendered in different font colors according to the value of the Severity field. Items with high severity
appear in Red font. Medium and low severity items appear in shades of gray.
The panes can be tiled horizontally or vertically via menu options located in the drop-down menu of
Refresh.
When using a license that enables it, this view incorporates the Bulk Edit feature. You can select multiple
items by checking the box next to the ID, and edits will apply to all the checked items. Export operations
are not affected by the selection of items for Bulk Edit.
The toolbar in the Table view displays some information about the results returned by the current
query:
Note
Administrators can set a limit in the system configuration on the number of items that can be loaded.
The default maximum is 3000 items. The limit does not apply when the Tree presentation option is
used to view the items.
• Load all link. This appears only if the number of items loaded in the table is less than the total number
of items found and less than the maximum number of items allowed in the system configuration.
When the number of items to be loaded exceeds the configured limit, the link label reads Load first
NNNN where NNNN is the configured limit on the number of Work Items that can be loaded in the table.
(For example: "Load first 3000").
Tree view
Tree view is similar to the Table view, except the set of retrieved items is presented as a tree structure.
Top level nodes are the items retrieved by the current query. If these items have other items linked to
them, their nodes can be expanded to show the linked Work Items. If a child item has one or more items
linked to it within the scope of the Depth query parameter, its node is expandable and the linked items
appear as child nodes.
In the Tree view, the Tree View Configuration has several additional fields that let you specify the
role(s) of linked items, the maximum number of link levels to search, the direction of linking, whether or
not to include repository commits in the search results, and whether or not to filter all levels.
Tip
• You can also edit some fields directly in the tree.
• Hold Ctrl and left click to select multiple Work Items.
• Hold Shift and left click to select a range or Work Items.
Caution
This view can require significant system resources to process, especially if the result set of the query is
large and/or there are many linked Work Items. The total number of items the query retrieves is limited
to 100,000 items by default.
If you configure the Tree so that your results exceed the default soft-limit of 5,000, a dialog box
appears asking you to adjust the configuration. You should refine the configuration so that the results are
less than this limit. If you absolutely must exceed the 5,000 item soft-limit, the results will be returned
until the hard-limit (100,000 by default) is reached. (These limits ensure that poorly crafted queries do
not consume too much of the Polarion server's resources.)
Tip
• When opening the table view of a LiveDoc with outline numbering enabled, Outline Number
appears as the first column unless already defined in the table configuration.
To hide the Outline Number column, customize the table in Table view.
• Polarion remembers a user's Tree configuration so they don't need to redefine it every time they
use it.
Tree direction: (Backlinked/Linked), link role, tree depth, whether to include commits and if it should
filter linked items.
Administrators can add or adjust the following property in the Configuration Properties section
( Administration Configuration Properties) to control whether or not Tree search results
include duplicate items. (Even if they're found in the nested tree of another item):
workitems.treeTable.removeDuplicateRoots=
Possible Values:
Note
This may result in some Work Items appearing multiple times in the list.
The following Work Items will appear in the base Tree search results.
• work_item_filter_S
• work_item_filter_A
The following Work Items will appear in the base Tree search results.
• work_item_filter_S
• work_item_filter_A
• work_item_filter_C
• work_item_filter_D
• work_item_filter_F
Deduplication limit
• com.siemens.polarion.ui.treeTable.deduplicationLimit=
(This property must be added to the polarion.properties file.)
◦ Prevents users from depleting server resources if they launch multiple Tree View queries with a
resource-intensive duplication stage.
If the deduplication limit is reached while the Tree View result is still being constructed, the query
is restarted, duplicate root removal is disabled, and users are notified that the tree might contain
duplicate roots.
◦ The property's value (500000000 by default) is the number of tree nodes and Work Items traversed
during the deduplication process.
This value must be high to ensure good results. (Otherwise the query will stop too soon.)
Add or adjust the following property in the polarion.properties file to control whether or not Tree
search results are refreshed automatically. Disabling automatic refresh prevents users from accidentally
triggering long-running search operations before correctly setting the Tree View Configuration. This may
improve system performance and stability in repositories with a very large number of Work Items:
com.siemens.polarion.ui.treeTable.autoRefreshEnabled=
Possible Values:
Search results are not refreshed automatically when the page is loaded, or if the Tree View
Configuration changes.
The search must be triggered manually, either by clicking the or the icons, before any results are
shown.
The Road Map view shows all Work Items in the current scope that are assigned a specific Time Point.
You can select a Time Point in the appropriate combo box to display relevant Work Items.
As in the Table viewTable view, the Query Builderappears here, and you can click any Work Item to
have its details display in the detail area where you can also edit the data.
If the license you are using provides it, this view also incorporates the Bulk Edit feature. You can select
multiple items by checking the box next to the ID, and edits will apply to all the checked Work Items.
Tip
Time points and the Road Map view can be used for time-box style project planning in cases where
the project manager feels that the Plans feature is more robust than is needed for the project.
Matrix view
The Matrix view is an interface for Polarion's traceability and impact analysis features. To establish
traceability, you must create links between Work Items, and/or between Work Items and repository
revisions. This can be done by editing individual Work Items as they are processed, or you can create
links for any number of Work Items using the Matrix view.
The view presents a grid of Work Items. The set of Work Items (or revisions) that appears in each axis is
determined by a query in the Search bar. In the context of the Matrix view, the set of Work Items contains
two sets of controls. One control is an upper set for the horizontal axis; the other control is a lower set
for the vertical axis. The intersection of the axes represents an actual or potential link between the two
items. If no link exists, the intersection is empty. If a link does exist, an arrow symbol appears indicating
the direction of the link (for example., from source, to target). You can click on the link symbol to pop up a
box with details about the linked items. You can navigate directly to any of the linked items by clicking on
the item name in the Link Details popup.
There are two properties in the polarion.properties file that define the maximum number of cells in a
Traceability matrix or a Variants comparison matrix.
Related Topics
With the Time Sheet view, team members can review and report the time they spend on Work Items
during a period of time which they specify in the relevant field. They can also use the view to edit time
already reported for individual items in Work Records. For more information, see Use the Time Sheet
View.
Related Topics
Work Items defined externally can be imported into Polarion and subsequently managed throughout the
application lifecycle. This capability is particularly useful when you have existing document-based assets
containing artifacts (requirements, test cases, etc.) that you need to leverage quickly and easily when
adopting Polarion. You can import from the following sources to create new Work Items in Polarion:
Microsoft Excel workbooks containing artifacts such as requirements, test cases and defects can be
imported to Polarion to create tracked and managed Work Items of the respective type. During import
you have the option to create Work Items in a Document or as items in the project's tracker. After import
into a Document, you have the option to use Word Round-trip to collaborate with external stakeholders
who use Microsoft Word. After import to the tracker, you have the option to use Excel Round-trip to
collaborate with external stakeholders who use Excel.
Tip
You can use indents or empty cells in Excel to create Work Item or Heading hierarchies
automatically upon import.
Preparing to import
Before beginning the import from Excel process, there are several things you should do or check:
• Check the configuration of the project into which you will import. Verify that the Work Item type
corresponds to the type of artifact you are importing. If necessary, customize the configuration to define
a corresponding Work Item type. For example, if the Excel document contains test cases, the target
project's configuration should define a Work Item type corresponding to test cases.
one row. (The worksheet can contain a header row.) Columns should correspond to Polarion Work Item
fields. Import of multivalued data is supported for some Polarion multivalued fields.
See Multivalued data and fields for more information.
Decide which Excel columns should map to which Polarion Work Item fields. If some columns have no
corresponding Work Item fields and you want to store their data in Polarion, it is necessary for a Polarion
or project administrator to add custom fields to the project configuration before importing. You are
able to specify field mapping during the import process. For information on which Work Item fields are
supported for Excel import, see Supported Work Item fields.
Tip
You can use indents or empty cells in Excel to create Work Item or Heading hierarchies
automatically upon import.
Identify the cell at which the import process should begin. You need to specify it in the import wizard.
Normally this is the leftmost cell on the first row after the header row, if a header row exists. However, it
can be any cell. For example, if you have previously imported artifacts from a worksheet, and new ones
have been added which you now want to import, you will need to specify the first cell on the first row
containing the added items.
• Check that images to be imported from the worksheet are in .gif, .png, .bmp, or .jpg format if you want
them to appear inline with other content. Images in other formats (.tiff for example) may still import,
but will be attachments (rather than appearing inline) and they will not appear in the import preview.
• Create Work Items with links to Work Items from another Polarion Project before importing. See Linking
Work Items Across Projects for details.
If your team prefers a document-centered approach to artifact management, you can import artifacts
from Excel and store them in a Document. This is the preferred approach if you subsequently need to
collaborate on artifact content with external stakeholders who use Microsoft Word. Your team will be able
to use the Word Round-trip feature.
Tip
You can use indents or empty cells in Excel to create Work Item or Heading hierarchies
automatically upon import.
Procedure
In the Configuration field, optionally select an import configuration. (Import configurations contain
rules that govern how artifacts are imported and mapped.)
4. In the File field, specify the locally stored Excel worksheet file you want to import and click Start. The
first page of the Import Excel Workbook wizard appears.
5. In the Import rows from sheet field, select the worksheet that contains the artifacts you want to
import in this operation. The list shows all worksheets in the specified workbook. You can only import
one worksheet at a time. For example, if a workbook contains requirements in one sheet and test
cases in a different sheet, you must do a separate import operation for each type.
6. In the Begin import at cell field, specify the cell at which the importer should begin importing
artifact data. The importer examines the worksheet and suggests a cell. The cell you specify in this
field should not be part of a header row. If the first column is some kind of artifact identifier, you
can begin importing from the second column, as Polarion assigns its own IDs to Work Items created
during the import process (see figure below).
Review the Table contains header field. The importer examines the worksheet and checks this field if
the sheet appears to contain a header row. (See figure below for an example of a header row.)
7. Click the as new Document link to indicate that Work Items should be imported into a new
Document. Two editing fields appear.
8. In the drop-down list control, select the space where Polarion should create the new Document,
and then enter a name for the new Document in the field provided. Note that the Document name
If your team prefers a tool-based approach to artifact management, you can import artifacts into Polarion
storing them in the integrated tracker rather than in a Document.
Procedure
1. Open the target project and in Navigation, select Work Items. The Table view appears.
2. In the Table view, on the toolbar, click and choose Import to open the Import Work Items
dialog box.
3. In the Format field of the dialog box, select xlsx: Microsoft Excel Workbook.
In the Configuration field, optionally select an import configuration. (Import configurations contain
rules that govern how artifacts are imported and mapped.)
4. In the File field, specify the locally stored Excel worksheet file you want to import and click Start. The
first page of the Import Excel Workbook wizard appears.
5. In the Import rows from sheet field, select the worksheet that contains the artifacts you want to
import in this operation. The list shows all worksheets in the specified workbook. You can only import
one worksheet at a time. For example, if a workbook contains requirements in one sheet and test
cases in a different sheet, you must do a separate import operation for each type.
6. In the Begin import at cell field, specify the cell at which the importer should begin importing
artifact data. The importer examines the worksheet and suggests a cell. The cell you specify in this
field should not be part of a header row. If the first column is some kind of artifact identifier, you
can begin importing from the second column, as Polarion assigns its own IDs to Work Items created
during the import process.
Review the Table contains header field. The importer examines the worksheet and checks this field if
the sheet appears to contain a header row.
7. Click Next when you are ready to continue. The field mapping page of the import wizard appears.
8. Map the worksheet columns to appropriate Work Item data fields. Use Preview to check the import
result, and modify mapping, create more import rules as needed, and optionally save the rules you
define for reuse with subsequent Excel imports.
9. Click the Import button to import the Excel artifacts and create Polarion Work Items in the project
tracker.
Caution
Before importing, link Work Items across projects to create Work Items with links to Work Items from
another Polarion project.
After you specify the scope of the data to import, the second page of the import wizard presents an
interface enabling you to:
The page initially presents a new import rule with field mapping:
Work Item Excel column Work Item field Conditional Custom field
import rule rule
Tip
You can use indents or empty cells in Excel to create Work Item or Heading hierarchies
automatically upon import.
Start by specifying what type of artifact you are importing from the Excel worksheet. Select from the list
of currently configured Work Item types. Next, specify the condition(s) for importing data as the selected
type. You can add more conditions by clicking the icon.
Next, specify how Excel columns should be mapped to Work Item fields. Proceed from left to right.
Column headers are worksheet column names. Cells contain drop-down lists from which you can select a
field name. It is not required to specify a field for every column. For example, if the worksheet contains
a column with some sort of ID for an artifact, you can skip mapping it because Polarion assigns IDs to all
Work Items created by the importer.
When you select some fields, they dynamically display fields for mapping date values in the worksheet to
Work Item field values. For example, suppose your Excel sheet has a column Priority with numeric values,
1, 2, or 3 which actually corresponds to your Polarion project's Severity field, configured with values Must
have, Should have, Nice to have. When you select Severity in the Priority column, the importer detects
the data values in the worksheet and presents a drop-down list for each value in which you can specify the
corresponding Severity field value.
Import values from Excel are used except in the following cases:
• If a column mapped to Author contains empty cells when imported, the user who executes the import is
set as the Work Item author.
• If some cells contain a user ID that doesn't exist in the target project, and you use direct mapping, the
Excel Work Item author is used and italicized.
(If you defined an author via custom mapping, your custom value will be used instead.)
In many cases, a single import rule gives the desired import result. (Remember that you can use the
Preview button at any time to preview the result of the import without actually importing. Preview shows
only the first 100 matching items found in the sheet.) If a single rule is not robust enough for your needs,
you can add more rules. To begin, click the icon labeled Add Work Item Rule. Another set of condition
rule plus field mapping is added to the page. Use it to add more parameters to the import configuration.
After Preview shows the import result you want, but before you click Import to trigger the import,
consider whether you or other team members might need to import another Excel worksheet using the
same rules and mappings you currently have specified. If so, click the gear icon in the header, choose Save,
and specify the name and scope of the import configuration.
You can define parent/child hierarchies for potential Work Items or Headings in Excel, then define import
rules in Polarion so that the relationships get automatically created when you import into a Polarion
Document.
Tip
You can use either indents or empty cells. Both accomplish the same result.
Procedure
1. Open the Excel sheet with the data you want to import.
2. Create Heading, Title and Description columns in the first row.
3. Enter the data you want to convert to Work Items and Headings.
4. Select the Title cell of an item that you want as a child Work Item.
5. Click the Indent icon so that the title text indents once to the right.
Note
• Polarion creates child Work Items from the indented rows during the import process.
6. Repeat this for all items that you want to define a hierarchy for.
7. (Optional) You can create Headings and Sub-headings the same way.
a. Add Yes to the Heading column for any row that you want to make a Heading or Sub-heading.
15. Select the Excel sheet you want to import in the Import rows from sheet drop-down.
16. Begin import at cell: Select the first cell to start from. (Choose the row below your heading row.)
17. Keep Table contains a header selected.
18. Select Separate multiple values if you want coma-separated data imported into multiple Work Item
field values.
19. Click as new Document.
Tip
Select , then Save to save the import configuration for future imports.
You can also set Work Item and Heading hierarchies using empty cells.
Procedure
1. Open the Excel sheet with the data you want to import.
2. Create Heading, Title and Description headers with empty cells between them.
Note
• Requirement 1 will appear as the parent, Requirement 2 its child, and Requirement 3 as a
child of Requirement 2.
• Chapter 1 appears as a Heading and Paragraph 1 as a Sub-heading.
Note
Available if you or someone in your Project has saved a previous import configuration.
9. Click Choose File, select your Excel worksheet and click Open.
10. Click Start.
11. Select the excel sheet you want to import in the Import rows from sheet drop-down.
12. Begin import at cell: Select the first cell to start from. (Choose the row below your heading row.)
13. Keep Table contains a header selected.
14. Select Separate multiple values if you want coma-separated data imported into multiple Work Item
field values.
15. Click as new Document.
• Import rows as: System Requirement if any of the conditions are met
Tip
Select , then Save to save the import configuration for future imports.
Your imported data appears as a Polarion Document and contains the same Work Item and
Heading hierarchy you set with empty cells in Excel.
Columns and data in Excel can be mapped to the following Work Item fields during import to Polarion.
Please see following notes on mapping multivalued data to multivalued fields.
Tip
You can use indents or empty cells in Excel to create Work Item or Heading hierarchies
automatically upon import.
• Assignee *
• Author
• Categories *
• Comments
• Custom fields *
• Description
• Due Date
• Hyperlinks *
• Initial Estimate
• Linked Work Items *
• Priority
• Remaining Estimate
• Resolution
• Resolved On
• Severity
• Status
• Time Spent
• Title
Note
* marked fields support the import of multivalued data. The import of multivalued custom fields is only
supported for enumeration types, not for primitive types. (Primitive types can still be imported as single
values.)
An Import Configuration is a saved import rule or set of import rules. Import Configurations can save
significant time and effort when there is a need to import multiple similar Excel worksheets. Import
Configurations can be saved in the global scope to make them available across projects, or in the project
scope to confine their availability to a single relevant project.
Procedure
3. When you have the result you want in the preview, but before you click Import, click the drop-down
icon (next to the workbook file name on page 2 of the wizard), and choose Save on the menu.
This launches the Save Import Configuration dialog box with the Create new configuration option
selected by default.
4. In the Scope field, specify the scope of the new Import Configuration (Global or Project).
5. In the Name field, specify a meaningful name for the new Import Configuration. This name will
appear to users in the specified scope in the Configuration field when they import Excel workbooks.
6. Click Save to create the Import Configuration.
Procedure
Note
You can modify the import rules loaded from the saved Import Configuration. You can optionally
save the modified import rule as a new Import Configuration, or you can overwrite the existing
Import Configuration with your changes (select the Update existing configuration option in the
Save Import Configuration dialog).
See Remove Unused Excel Import Configurations for more information.
It is possible to define multivalued data in Excel so that it can be mapped to multivalued fields in Polarion
Work Items, and multiple values written to such fields during import.
The following fields must be written in a special format using a specific pattern:
• Linked Work Items: pattern: "[role:][project/]id". External linked items pattern is:
"[role:]URL".
• Hyperlinks: pattern: "[role:]URL"
Past versions of Polarion have supported Work Item import from certain versions of Microsoft Project.
This is considered a legacy feature, and later versions of Microsoft Project are not supported. For more
information see Importing from Microsoft Project.
Every Work Item is part of a Project, and is planned and tracked with the Project. If a Work Item has
dependencies with another project, it is possible to show this using the Work Item Linking feature.
You can browse the Work Items in the current project in different views in the Work Items page: Table,
Tree, and Matrix. The views render different presentations of Work Items for different purposes such
as task management, project planning, traceability linking and so forth.
To browse Work Items, select the Project in the Open Project or Project Group dialog box, select the
Work Items topic in Navigation, and then select the desired view of Work Items from the view selector on
the page toolbar.
When you select a Work Item, its details appear in the lower half of the page, and various titled sections in
that section display information about the Work Item such as priority, status, who it's assigned to, when it
is (or was) started and when it will be (or was) completed.
The Work Item Tracker and Editor are where you find and edit existing Work Items.
The Work Item Tracker is where you search for, view, or even edit some Work Item fields right in the
table. Depending on the current view ( Table, Tree, and Matrix, for example), you may be able
to select multiple Work Items. The layout changes with the selected view. If your license enables the Bulk
Edit feature, you can select multiple items by checking the box next to the ID, and edits will apply to all the
checked Work Items.
The Work Item Editor displays detailed information about the Work Item selected in the Work Item
Tracker. You can scroll, resize, or maximize the pane to browse all available information.
• Some fields are editable without the need to click Edit. Hover over a field for a moment to see if it can
be edited in place.
• You can quickly jump to different sections of the Work Item using the top toolbar buttons below:
◦ Instantly scrolls to the Comments section where you can add and view any comments about
the Work Item.
◦ Instantly scrolls to the Linked Work Itemsection where you can view all the Work Item's links
(if any).
◦ Instantly scrolls to the Attach files to a Work Item section where you can view and access any
files attached to the Work Item.
◦ Reduces or increases the number of fields shown on the Work Item Editor.
◦ Lets you view the Work Item's change history. You can drill down into any revision of the Work
Item.
◦ Change what Work Item in the table appears in the Work Item Editor.
◊ Launch the selected Work Item in the Work Item Editor in a new browser tab.
Which fields are displayed or hidden are defined by an administrator in the Form Filters section of Form
Configuration.
Tip
Why can't I edit? Your ability to edit Work Items depends on the role and permissions assigned to you
by the System Administrator or Project Administrator. If you do not have write permissions, the buttons
and links that trigger edit mode do not appear, or are disabled in the interface.
You can edit certain fields like Title and Priority of a Work Item directly in the Work Item table. Simply
activate a field for editing by clicking it two times, that way you can quickly edit a field without having to
open the Work Item in the Work Item Editor.
When browsing, you can sort the Work Items displayed in the Table view by clicking on the column
header of the data column you want to sort.
For example, click the header of the Status column to sort the items in the table according to the current
status of the Work Items.
If you have multiple fields that you want to sort a Work Item table with, you can define a sort order.
2. Select an existing Column in the Columns Shows section or an Available Column and click Add →.
3.
Select a Sort Direction.
4. (Optional) Change the Sort Order.
Tip
• Outline Numbering cannot be used with other sorting options and disables them if its selected.
• To remove a column from the Sort Order select the column in the Columns Show list and select
None as its Sort Direction.
5. (Optional) Click Save as... and select whether this sorting option is the Default for all project users,
or is only visible to you as a Personal custom configuration.
6. Click Apply.
You can customize the table of Work Items that appears in the Table, Tree, and Road Map views
to show different Work Item fields as table columns. You can customize the table content for the current
session, or create one or more saved column configurations which you can switch as needed. You can also
change the default column layout for all users in the scope where you are working (project, project group,
or repository), assuming you have the necessary permissions.
System Administrators can adjust the maximum number of Work Items displayed in the tracker by adding
the following property to the polarion.properties file:
com.polarion.ui.table.hardLimit=X
The default setting in Polarion, (without using the above property), is 10,000.
To quickly show or hide table columns for the current session, right-click on any column name. A menu
appears listing all currently-shown columns. Columns currently visible in the table show a check mark.
Click on a column name in this menu to switch its visibility for the current session.
You can show more columns in the table for the current session by clicking More in the menu and adding
columns from the Available Columns list to the Columns Shown list of the Customize Work Items Table
dialog box. (Multi-selection works here.)
You can customize the Work Items table to show any set of columns in any desired order, specifying the
sorting level and direction of any column. You can save any custom table configuration you create and
reuse it at any time. You can optionally save multiple named column configurations for different personal
needs. If you have the necessary write permissions, you can save a custom table column configuration
as the default for all users of the current Project, Project Group, or Repository, depending on
which scope you are working in when you create the custom configuration.
2. In Navigation, select Work Items, and on the page toolbar select the Table view if it is not already
the current view.
If you want to see the Table view of Work Items contained in a Document, open the Document
and select Table on the Views menu.
3. In the Table view, on the Page Actions menu, choose Customize Table.
Tip
The Customize Table dialog box supports multi-select.
• Hold Ctrl and click on additional items to add or remove them.
• Select a starting item, hold Shift and select another item. (All the items between them will also
be selected.)
• Ctrl+A to select all items.
5. (Optional) Change the appearance order of columns in the Columns Shown list by selecting a
column and changing its position in the list using the arrows (or keyboard shortcuts shown in
tooltips). Top to bottom in the list corresponds to Left to Right in the table.
6. (Optional) Set properties for some or all columns. Select a column to show its properties settings.
• Width: Displays the width of the column in pixels. Enter a whole number value such as 60.
Tip
Outline Numbering cannot be used with other sorting options and disables them if its selected.
7. Click Save As to save the configuration of specified columns and column properties.
8. In the Save Custom Table Configuration dialog box, choose one of the following options:
• Default for all users in scope: Saves your changes as the default table column layout and sorting
for all users in the current scope (project, project group, or repository). Users are able to customize
for the session or invoke their own saved column configurations.
• Personal custom configuration: Saves your changes to a named personal table column
configuration that you can invoke on the Work Items table any time. Specify a name in the Name
field.
9. Click Save to complete the customization operation.
Tip
If the table-setting.xml configuration file is customized externally, and settings in the Customize
Work Items Table dialog box are also changed, the settings from table-setting.xml are not
reflected in the table. Only the settings in the dialog box are reflected. To also reflect settings from
the configuration file, click Reset in the dialog box.
The Description field of Work Items can contain tables. By default, the text in table cells does not wrap and
the text in some cells may appear truncated when you browse the description. In this case you can switch
the Wrap Text feature of Work Item tables.
Procedure
2. In the Table view of Work Items, right click on any column header in the upper part of the table of
Work Items to display the Columns menu.
3. On the Columns menu, choose Wrap Text. When text wrapping is active, a check mark appears in the
menu items.
In many development teams, as a team member you may work in different contexts at different times.
You may sometimes function as manager, and other times as developer or a tester. In these different work
contexts, it can be useful to only view and access what is most needed for that role, and have everything
else out of the way temporarily.
Your system or project administrator can work with teams to configure interface Views for different work
contexts that adjust the user interface to show only what is needed for each work context.
The Views list appears in the Navigation pane's Tool view when you are logged on (click the Tool icon in
the upper left corner of the pane). When you first log on, the default interface View is active, and you have
access to all topics and Work Item fields allowed by the configuration. In the default configuration the list
provides several other interface Views that you can switch to as needed:
• Requirement Engineer
• Developer
• Manager
If you see different names in the Views list, keep in mind that the list may have been reconfigured by your
administrator for your Polarion system or the particular project you have open.
Each interface View can show its own set of topics in the Navigation pane. Each interface View can also
show a different set of fields on the Work Item detail form, a different layout of the visible fields, and can
control which fields are editable. What each interface View presents, and how, is controlled by the View
configuration which can be customized by an administrator. For information, see Configure interface
Views.
• On the Work Item toolbar, click to switch the level of detail displayed on a Work Item.
Which fields are displayed or hidden are defined by an administrator in the Form Filters section of Form
Configuration.
The Work Item details panel includes a section titled Linked Work Items. This section displays a listing of
Work Items of all types that are linked to the Work Item you are viewing. If your installation is licensed and
configured to use multiple repositories, the listing also displays any linked items that reside in a different
repository from the one you are using. You can open any item listed by clicking on its title in the listing.
(You may not be able to open a linked item in a different repository if you do not have access permissions
for the other repository.) To open all items listed in this section which are hosted in the current repository,
click the small icon in the lower right of the section footer (tooltip: Browse all items on this server in the
Table tab).
Linked Work Items are also displayed above and/or below the title of the current Work Item in the viewer/
editor. You can easily see all the incoming and outgoing links. Clicking on any linked item opens it in your
browser.
Polarion has extremely powerful Work Item query capabilities, thanks to its integration of the Apache
Lucene query engine. Lucene is mainly a command-line tool. Users who know Lucene query syntax and
Polarion's Work Item fields and variables can run command line queries in the Work Item Query Builder.
You can user the Query Builder's graphical assists to easily build simple and complex queries to search for
and retrieve the Work Items you want in any view of the Work Items topic, as well as in dialog boxes such
as the Work Item Picker where you query for Work Items.
Tip
You can also use the Query Builder to search for Documents, Pages, Plans and Test Runs.
Every view in the Work Items topic contains the Query Builder in the toolbar or header. You construct
queries by visually adding query filters to the Visual Query Builder. Query filters visually represent
parameters of the underlying command-line syntax.
When you enter the Work Items topic, one default query filter is shown in the Visual Query Builder:
Unresolved. This filter, alone, retrieves all unresolved Work Items. To get the results you want, you can
either keep this filter and add more to refine the results, or remove it and start adding different filters.
When you click to add an filter, a pop-up bubble shows you three lists: often-queried fields (Favorites),
recently queried fields (recent), and all fields, including custom fields. Fields are listed by name, so you do
not need to remember or use field IDs as you must for command-line queries.
Add filter Work Item Clear all Select field Select field
Table view values
Caution
• When you Construct queries graphically, for some fields like document.id, the name the of space
or document.id must contain spaces in an escaped format.
Example after using the "Convert to Text" option:
◦ document.id:(Design\ documents/Best\ Engineering\ Practices)
Where Design\ documents is the Polarion Space (folder) and Best\ Engineering\
Practices is the Document ID that contains spaces in the name.
• Escaping characters with a \ in a graphical query is not possible because the \ is escaped, creating a
\\ and that's a different escape sequence.
• You can clear all visual query filters or command-line text from the Visual Query Builder by clicking the
X icon near the right-hand end of the tool.
• Close filter pop-up bubbles by clicking anywhere outside them.
• If there are many visual query filters and some are scrolled out of view and/or condensed, you can see
the condensed names and/or access and edit them using the list of all current filters. To display the list,
click the drop-down arrow on the left side of the query builder. You can also use the list to remove any
query filter from the Query Builder.
• The Recent section in the query filter pop-up displays a list of the fields and field values you selected
most recently. The items in this list can help you create often-needed queries and eliminate the need to
save them.
• You can convert any graphically constructed query to command-line text by clicking the drop-down
arrow at the right-hand end of the query builder and selecting the Convert To Text option. This lets you
build queries visually and copy the syntax to use it elsewhere, for example, in the Query parameter of a
LiveReport Widget.
• You can use the Query Builder in command-line mode by removing all graphical query filters and typing
in valid command-line query syntax.
• You can use both visual query filters and command-line text in the query builder. See Combine Text
with Visual Queries.
• The URL displayed in your browser contains a parameter query, which contains the full command-line
syntax of the current query in the Query Builder. You can copy this parameter and use it in the query
parameter of LiveReport Widgets or other places where Lucene query syntax is required.
• The Visual Query Builder contains an SQL filter, which can be used alone to filter the Work Items table
by an SQL query only, or in conjunction with other visual query filters. For more information, see Use
SQL Queries to Retrieve Work Items.
Note
Invalid SQL commands and symbols: (Implemented for security purposes)
◦ Some SQL commands and symbols are not allowed in SQL queries.
System Administrators define what's invalid in the polarion.properties file with the following
property:
◊ com.polarion.platform.sql.invalidCommands
◦ Exceptions from PostgreSQL are not propagated to client-side error messages. Instead, they are
added to the logs as ERRORs.
◦ See the default list for this property by searching for it in the System Configuration Properties
Reference document.
Related Topics
Overview
Save and share queries
Commonly needed queries can be saved and reused. Saved queries can be global in scope (that is
accessible to all portal users), limited to one Project (accessible only to users who have a project role
assigned), or limited to access by you only.
Procedure
1. Click the drop-down arrow at the right-hand end of the Visual Query Builder, and click Save Current
Query.
2. In the Save Query dialog box, enter a descriptive name, and select whether the saved query should
be accessible globally by all portal users (Global), project locally by users having a project role
(Project), or only by you (User).
You can rerun any saved query to which you have access.
Procedure
1. Click the drop-down arrow at the right-hand end of the Visual Query Builder.
2. In the pop-up bubble listing available saved queries, click on the name of the query you want to run.
Tip
You can copy the command-line syntax of a saved query to your clipboard by pressing your Ctrl or
Cmd key, and then clicking the saved query name.
By default, Polarionruns a system default query specified in the system configuration whenever you access
the Work Items Table. You can override that default and set any query as your personal default query, to
be run whenever you access the Work Items Table. Your personal default query is also used wherever the
system default query is normally run.
Procedure
1. Use the Visual Query Builder tool to construct the query you want.
2. Click the drop-down control on the right-hand side of the query builder, and in the pop-up panel, click
Save as Default (see the screenshot in the Construct queries graphically section).
3. Confirm the action in the dialog box that appears.
You can change your personal default query any time by repeating these steps with a different query.
Suppose you expand the Work Items topic in Navigation, and then select one of the types, for
example, Requirement. Then, suppose you specify a query like Status: Draft, which filters the table to
show only Requirements items with Draft status. If you now select a different type in Navigation, for
example, Test Case, by default your query Status: Draft is preserved and the table is filtered to show Test
Case items with Draft status. This may or may not be what you want when you switch the context.
The same is true in a larger context switch. For example, you might be looking at the table showing
Requirements with Draft status, and then switch to a different project. Or you might be looking at the
Table view of a Document, and switch to a different Document. In all cases, your current query is preserved
and the table in the new context is still filtered to show Requirements with Draft status. In the new
context, the query results might not be what you need.
Whenever you switch to a context in which the current query's result may no longer be valid, a warning
icon appears in the Visual Query builder. Clicking the icon displays a dialog box in which you can specify
the behavior you prefer when switching contexts.
The dialog title and text vary depending upon the context switch (switching between Work Item types as
opposed to switching to a different Document, for example), but the options are the same.
• Always Use Default Query: When you switch to a different context, the default system query for the
context is always executed. For example, when switching to a different Work Item type, the Work Items
Table always shows only Work Items of the selected type in the table. Any user-defined query present in
the Visual Query Builder before the switch is deleted.
• Always Keep Current Query: The system preserves any user-defined query present in the Visual Query
Builder before the switch. Be sure you are aware of the effect of the preserved query. You may want to
modify or remove it after the context switch.
Overview
This topic and subtopics are for advanced users who query for Work Items using command-line queries in
the visual Query Builder, macros, widget scripts, or in API usage.
Polarion's query language is essentially the same as that of Apache Lucene. The syntax is documented in
the Apache Lucene Syntax Documentation, available on the Apache web site.
The same query language is applicable in a number of administrative tasks such as customization of
configuration files that contain query expressions, or filters, or attributes that consist of a query expression.
Existing queries that use any of the constructs mentioned below still work, but are now considered
deprecated and long-term support for them is not guaranteed. It is recommended that you update all such
usages in saved queries, macro and page parameters in Wiki pages, API calls, etc. to the recommended
form.
Polarion's query engine is based on Apache Lucene. Consequently, query syntax in Polarion is essentially
the same as that of Lucene. You may want to download the Lucene Documentation. The following table
lists some syntax constraints that are commonly needed when constructing queries in Polarion.
title:word
* - severaltitle:ab* - finds Work Items having words starting with 'ab' in the
title fieldtitle:ab*c - finds Work Items having words in the title field starting
with 'ab' and finishing with 'c'
Lucene expands all the wildcards to matching statements. Thus, if you type
title:t*it will be expanded by Lucene to: title:the OR title:test
OR title:task OR...
Fuzzy/proximity search Tilde (~) is used for a fuzzy/proximity search. You should seldom need to use
~ it.
Range Searches { } [ ] [ ] – Specifies the range in dates or numbers,
{ } – Will find all Documents whose titles are between specified terms,
exclusive.
Example:
created:[20120208 TO 20120222]
finds Work Items created between 08 Feb 2012 and 22 Feb 2012
AND == &&
OR == ||
NOT == !
+/- may be used for the explicit requirement of having the record found or
excluded.
Grouping () Group statements using parentheses.
• If you want to search for Work Items in any LiveDoc inside of a specific
Space, you can use a query with escaped whitespace characters and a
wildcard *.
(For example, document.id:My\ Space*)
If you have used the visual query elements in the Query Builder to create a query, you can optionally
append free-form textual query syntax. When combining visual and textual query elements, keep the
following points in mind:
• The free-form part of query is usually connected syntactically with the visual filters by the AND operator.
For example, if you have two visual filters [Type:Requirement][Assignee:Me] (visual filters
denoted here by square brackets), if you append text severity:must_have, your Query
Builder line will look like [Type:Requirement][Assignee:Me] + severity:must_have,
and will be treated by the query parser as: type:requirement AND assignee.id:$me AND
severity:must_have.
• Appending text to visual filters with the OR operator causes the leading visual filters to be treated
syntactically as if they were surrounded by parentheses.
For example, if you have two visual filters [aa:xx][bb:yy] (visual filters denoted here by square
brackets), if you append text OR cc:zz, your Query Builder line will look like [aa:xx][bb:yy] + OR
cc:zz, and will be treated by the query parser as: (aa:xx AND bb:yy) OR cc:zz.
• If the Query Builder is cleared of all visual filters, you can start the free-form part of a query with an
operator. However, AND and OR are ignored. Operator NOT at the beginning of a query is parsed as you
would expect.
You may sometimes access the Work Items table via a link in an email or a shortcut containing a query,
or via a saved query. If the query you are opening was originally constructed with visual query filters, the
visual filters appear in the Query Builder when you access the table via the link or shortcut, and you can
subsequently edit the query by modifying the visual filters.
If the query you open contains any filters that cannot be parsed into visual filters, the filters which can be
rendered visually are so rendered until a filter that cannot be parsed into a visual filter is encountered. The
remaining filters are rendered as a text string. You can then modify the query any way you want, editing,
adding or removing visual filters, and/or editing, removing, or modifying the text string.
Tokenization
Polarion supports two different tokenization algorithms. The system property search.wordBoundaries
can be used to select between them.
• splitByPattern
The input is split to words using a regex pattern. This is the default.
• standard
The word boundaries are defined according to the Unicode standard.
Note
• Always use standard for Asian languages.
• Changing the value of this property requires a reindexing of Polarion data because this
configuration controls how the data are indexed.
This is the default tokenization. However, it is not convenient for languages that do not use white
space between words. The indexed text is split around white spaces, and from the remaining character
sequences all leading and trailing non-alphanumeric characters (anything that is not a letter or number)
are removed.
Note
For advanced users: This splitting is done using a regular expression and
java.lang.String.split(String). It is possible to configure a custom regular expression that
should be used via the system property search.wordBoundaries.splitByPattern.
EXAMPLES:
(Term for title.1 field is always the same as the title itself.)
Result (standard
Item Title Terms for "title" field Query tokenization)
Mary had a little Mary, had, little, lamb title:mary found
'lamb'.
title.1:mary not found (title.1's term is
"Mary had a little lamb")
title:mary* found
title.1:mary* found
Standard tokenization
This method splits text into words according to the Unicode standard. To use this method of tokenization,
use the system property search.wordBoundaries=standard.
Examples:
(Term for title.1 field is always the same as the title itself.)
Result (standard
Item Title Terms for "title" field Query tokenization)
Mary had a little Mary, had, little, lamb title:mary found
lamb.
title.1:mary not found (title.1's term is
"Mary had a little lamb")
title:mary* found
title.1:mary* found
SW_ngcb_simulatio SW_ngcb_simulation title:SW not found
n
title:ngcb not found
title:SW_ngcb not found
title:SW_ngcb* found
title.1:SW_ngcb not found (title.1's term is
"SW_ngcb_simulation")
title.1:SW_ngcb* found
WI-1234 WI-1234 title:WI found
title:1234 found
title:WI-1234 found (matches titles
containing "WI" or "1234")
Querying for items in a particular state with regard to approval has a special syntax - see the following
examples.
Tip
In the Work Items table, create a query using the visual query builder, selecting the Approval field
and setting the desired parameters. In the helper panel, click Copy to Clipboard to access the query
including the special syntax.
You can query for Collection, Document, or Project Baselines with the following:
• baseObject:collection/*
Tip
It is possible to display Collection IDs as a column in the Collection table.
• baseObject:document/*
(Searches for all Document Baselines for the Formula 3 document in the Specification Space.)
• baseObject:project
#set($q = '"')
#set($query = "project.id:$document.projectId AND (baseObject:${q}document/
$document.relativePath$q)")
#set($sort = "~baseRevision")
#set($baselines =
$transaction.baselines().search().query($query).sort($sort))
<table class="polarion-rpw-table-content">
<tbody>
<tr class="polarion-rpw-table-header-row">
<th>Baseline Name</th>
<th>Document Link</th>
<th>Base Revision</th>
</tr>
#foreach($baseline in $baselines)
<tr class="polarion-rpw-table-content-row">
<td>$baseline.fields.name.render</td>
<td>$baseline.fields.baseObject.render.withLinks</td>
<td>$baseline.fields.baseRevision.render</td>
</tr>
#end
</tbody>
</table>
You can query for Work Items contained in Documents by Document ID, Document Title, and by
Outline Number (with some limitations pertaining to historical revisions ‒ see details later in this topic).
Search by Document ID
Use the document.id index field to query for Work Items contained in a specific Document.
Searches for Work Items contained in the named Document in the default space.
Note
The _default space name should not be specified. You only need to specify it in the query parameter
of wiki macros like the {workitems} macro.
Searches for Work Items contained in a Document named Functional Specification in the Requirements
space.
You can for Work Items from multiple Documents by title by using the following boolean query:
Caution
If you use document.title:"Document_name_1" "Document_name_2" without parentheses,
you'll also return results that contain Document_name_2 anywhere in their content.
You can query for Outline numbers in Documents using the special index field outlineNumber.
Note
By default, it is only possible to search in the HEAD revision, not in historical revisions or Baselines. For
more information, see Query by Outline Number in historical revisions.
The Outline Number field can be sorted by this index field. Sort is by document.outlineNumber, and
wildcards are supported.
Examples:
• outlineNumber:1.1.*
All items in the current scope with outline number on level 1.1.
• NOT HAS_VALUE:resolution AND document.id:"Specification/Functional
Specification" AND outlineNumber:1.1*
Unresolved items with outline number on level 1.1 in a Document named Functional Specification
located in the Specification space.
• outlineNumber:("PROJECT/SPACE/ID", "2*")
When searching for content of a particular outline number, the Document to search within can also be
specified.
When working within the Document scope (Using the filter in the document editor, the table or tree tabs),
the Document is automatically added to the query.
Tip
Specify a Document whenever possible (in all places other than in the Document scope), otherwise the
outline number query will search through all the Documents in the entire repository.
Note
Outline number queries only work when the number of Work Items that contain matching outline
numbers is not greater than the value of the "luceneMaxClauseCount" system configuration
property.
By default, it is only possible to query on, or sort by Work Item Outline Number in the HEAD revision.
The historical index for outlineNumber is disabled because in large data systems, having it enabled can
greatly increase the index size, leading to significant utilization of the Java heap space and running out
index disk storage capacity.
Note
Building of the historical index for the outlineNumber field was not configurable prior to version 22
R1.
There can sometimes be a need to query for Work Items that are linked by another Work Item according
to the link role.
• linkedWorkItems
• backlinkedWorkItems
These exist in different projects, and both have links to/from other Work Items (for the purposes of this
example, it doesn't matter in which projects the linked items live).
You can search for Work Items that are associated with one or more Plans. There are some limitations,
which are described below.
Caution
The criteria defined by a PLAN query must match less items than the limits defined in the following
properties in the polarion.properties file:
For wildcard queries like PLAN:* or PLAN:myProject/*, you can avoid this limitation by adding AND
to the PLAN query for wildcard queries, but these additional query components must also match less
than 100 000 Work Items.
The following table has some examples of how Work Item Plan queries behave if queries hit the
configured limits described above.
(QUERY) AND PLAN:(*) Will fail only if there are more than 100 000 Work Items
matching the QUERY, or if more than 20 000 Work Items
matching the QUERY are planned. (QUERY is a placeholder for
any query).
(QUERY) AND NOT PLAN:(*) Will fail only if there are more than 100 000 Work Items
matching the QUERY or if more than 20 000 Work Items
matching the QUERY are planned. (QUERY is a placeholder for
any query).
You can build queries to search for Work Items linked to a test record in a particular Test Run using the
TEST_RECORDS filter.
This can be particularly useful when creating report pages. For example, a test manager might use it to
query for what defects were part of some test results.
Require
Component Description d Attributes
test run Identifier of the Test Run whose YES N/A
test records should be queried
for linked Work Items. Format:
project ID/Test Run ID.
test result The kind of results to search for. NO testResultId - identifier of a kind
of result, for example,"failed",
"passed", "blocked"
Examples:
Search for test cases planned for Initial System Verification Test, but not executed yet:
Search for test cases executed by mTest in the last week in Full System
Verification Test: TEST_RECORDS:("drivepilot/Full System Verification
Test",@any,"mTest","$today-1w$ TO $today$")
The Polarion query system provides a special $today$ constant that can be used in query strings to
retrieve Work Items updated on the current date. This can be useful for creating shortcuts.
• $today - SHIFT$: actual date minus time frame specified by SHIFT (see examples below)
• $today + SHIFT$: actual date plus time frame specified by SHIFT
• Nd: N days, where N is an integer value. For example, 14d represents a time frame of fourteen days
• Nw: N weeks
• Nm: N months
• Ny: N years
The following example searches for items created during the previous week:
Spaces between $today and SHIFT$ are ignored, so expressions like $today-3w$ will work.
You can gather helpful information using SQL queries. Here are some examples:
Note
Sample queries use Postgres-specific operators and functions (JSONB) to fetch data and may change
from one version of Postgres to another.
• We recommend you use json operators and functions included in the ISO SQL Standard 2017 for
struct queries.
• The jsonb operators and functions are specific to Postgres and backward compatibility is not
guaranteed for these queries.
• The behavior or syntax can change from one version to another and may break reports without
further notice.
Tip
• Fetch records via test parameters
• Fetch records via Test Steps and their results
• Fetch Documents by their signature status
• Fetch Work Item via parameters within Test Steps
• Fetch record via Test Record custom fields (like time and date)
Find all Test Cases in project 'drivepilot' that ran with "Browser" as "Chrome" test parameters:
select TESTRUN.C_URI
from TESTRUN
inner join PROJECT on PROJECT.C_URI = TESTRUN.FK_URI_PROJECT
inner join STRUCT_TESTRUN_RECORDS on TESTRUN.C_URI =
STRUCT_TESTRUN_RECORDS.FK_URI_P_TESTRUN
inner join WORKITEM on STRUCT_TESTRUN_RECORDS.FK_URI_TESTCASE=WORKITEM.C_URI
where true
and PROJECT.C_ID='drivepilot'
and TESTRUN.C_TYPE = 'manual'
and STRUCT_TESTRUN_RECORDS.C_RESULT='passed'
and STRUCT_TESTRUN_RECORDS.C_TESTPARAMETERS->>'Browser' similar to '%Chrome'
Retrieve Test Run Records that match ['Drive Train Type'] with ['4WD] and 'Passed':
select TESTRUN.C_URI
from TESTRUN
Retrieve Test Case information in Test Runs with 'Passed', 'Failed', and 'Blocked' test results:
select TESTRUN.C_URI
from TESTRUN
inner join PROJECT on PROJECT.C_URI = TESTRUN.FK_URI_PROJECT
inner join STRUCT_TESTRUN_RECORDS on TESTRUN.C_URI =
STRUCT_TESTRUN_RECORDS.FK_URI_P_TESTRUN
inner join WORKITEM on STRUCT_TESTRUN_RECORDS.FK_URI_TESTCASE=WORKITEM.C_URI
inner join CF_WORKITEM on CF_WORKITEM.FK_WORKITEM=WORKITEM.C_PK
cross join jsonb_array_elements(STRUCT_TESTRUN_RECORDS.C_TESTSTEPRESULTS)
with ordinality step_result_arr(step_result, step_result_index)
cross join jsonb_array_elements(CF_WORKITEM.c_testSteps_value) with
ordinality steps_arr(steps, steps_index)
where true
and PROJECT.C_ID = 'drivepilot'
and TESTRUN.C_ID='Initial System Verification Test'
and step_result_arr.step_result->>'result'::text = 'failed'
and steps_index=step_result_index
Fetch Test Run details from project 'drivepilot' for Test Steps with the '%Start AutoPilot%' string
and 'Passed' results:
select TESTRUN.C_URI
from TESTRUN
inner join PROJECT on PROJECT.C_URI = TESTRUN.FK_URI_PROJECT
inner join STRUCT_TESTRUN_RECORDS on TESTRUN.C_URI =
STRUCT_TESTRUN_RECORDS.FK_URI_P_TESTRUN
inner join WORKITEM on STRUCT_TESTRUN_RECORDS.FK_URI_TESTCASE=WORKITEM.C_URI
inner join CF_WORKITEM on CF_WORKITEM.FK_WORKITEM=WORKITEM.C_PK
cross join jsonb_array_elements(STRUCT_TESTRUN_RECORDS.C_TESTSTEPRESULTS)
with ordinality step_result_arr(step_result, step_result_index)
cross join jsonb_array_elements(CF_WORKITEM.c_testSteps_value) with
ordinality steps_arr(steps, steps_index)
where true
and C_ISTEMPLATE is NULL
and PROJECT.C_ID = 'drivepilot'
and TESTRUN.C_ID='Initial System Verification Test'
and step_result_arr.step_result->>'result'::text = 'passed'
Fetch the number of Work Items where 'Autopilot' is the expected result parameter:
select COUNT(*)
from cf_workitem cross join
jsonb_array_elements(cf_workitem.c_teststeps_value) with ordinality
test_steps_arr(step, step_index)
cross join jsonb_array_elements(test_steps_arr.step-> 'testParameter' ->
'expectedResult') with ordinality testparameter_expectedresult_arr(param,
param_index)
where testparameter_expectedresult_arr.param::text similar to '%(Autopilot)
%'
Fetch record via Test Record custom fields (like time and date)
Fetch all records ran between '1970-01-01 13:13:00' and '1970-01-01 15:17:00':
You can only create new Work Items if the relevant permissions are granted to your user profile:
• You must be granted the CREATE permission for Work Items in the project.
• If you are denied the MODIFY permission for any Work Item required field(s), you cannot create a
new Work Item unless the project configuration specifies a default value for these required fields. The
restricted field(s) are assigned the default value in new items, and you cannot modify the field value in
the new items. For details about this restriction, see Work Item Field Permission Restrictions and New
Work Items.
If you find you cannot create a new Work Item, contact your administrator and review your permissions.
See Duplicate to copy an existing Work Item from the Work Item tracker or a LiveDoc.
For information about creating Work Items from content in Documents, see Working with Documents:
Work Items in Documents.
Tip
Administrators can configure Quick Create so users can create Work Items right from the Navigation
Header.
Procedure
1. Open the project where you want to create a new Work Item.
Tip
• Enter a Title and Description for your Work Item so that it's readable in all Polarion views.
• See How Work Item Titles are created and updated to learn how Polarion auto-creates and
updates Titles if they are not explicitly defined.
One or more Quick Work Item icons appear to the left of the Create ( ) icon. These represent the first
Work Item types defined in your system configuration. These are in the same order that appears under the
Work Items topic. Click one of the icons to create a new Work Item of the respective type.
Tip
It is also possible to create a new Work Item using the icon in the Work Item Editor. Its menu
contains special items for creating a new Work Item and linking it to some other existing one at the
same time. For more information, see Actions.
New Work Items can be created in Microsoft Excel in an Excel document that has been exported from
Polarion. See Using Excel Round-trip.
You can also create a new Work Item by adding workitem?form_mode=create to your URL address.
The Work Item type and any string field can also be added to the address and their values will be
autofilled when the new Work Item appears. All other fields must be entered manually.
Example:
polarionservername.com/polarion/#/project/mr_demos/workitem?form_mode=
create&form_field_type=defect&form_field_occurredInVersion=123
You can edit Work Items in several places, but use the Work Item Editor (form) for extensive edits to a
single artifact.
Tip
• To quickly edit different fields or values in multiple Work Items, you can edit them inline right in the
Work Item tables.
• To edit the same fields in multiple Work Items at once, use Bulk Edit..
(Especially useful for assigning multiple Work Items to the same person, or setting the same Status,
Priority, or Start/End date for several items.)
• Even if you have permissions that let you modify Work Items, some fields might be set to read-only.
3. Edit the desired fields and click Save. (Or Save and Suspect)
Tip
• Some fields are editable without the need to click Edit. Hover over a field for a moment to see
if it can be edited in place.
• You can quickly jump to different sections of the Work Item using the top toolbar buttons below:
◦ Instantly scrolls to the Comments section where you can add and view any comments
about the Work Item.
◦ Instantly scrolls to the Linked Work Item section where you can view all the Work Item's
links (if any).
◦ Instantly scrolls to the Attachments section where you can view and access any files
attached to the Work Item.
◦ Reduces or increases the number of fields shown on the Work Item Editor.
◦ Lets you view the Work Item's View Work Item History. You can drill down into any
revision of the Work Item.
◦ Change what Work Item in the table appears in the Work Item Editor.
◊ Launch the selected Work Item in the Work Item Editor in a new browser tab.
A Work Item can contain a number of data fields. Click to minimize the level of details on the Work
Item toolbar.
(Which fields are displayed or hidden is defined by an administrator in the Form Filters section of Form
Configuration.)
Polarion remembers your preference and displays all other Work Items with the same detail level.
The Work Item editor contains various fields with drop-down menus or lists from which users can select
a value for the field. In some cases, the list of items can be quite long, slowing the page response while
populating. Long lists can also be difficult to browse.
Tip
• Select the drop-down and start typing what you want to speed up the filtering process.
• List filtering works in all drop-down list/combo boxes in Polarion, including dialog boxes. The default
number of items loaded to lists is configurable by an administrator.
You can edit some Work Item fields directly in the Table and Tree Work Item tables.
• Click Cancel to revert edits or Save / Save and Suspect/CTRL +SHIFT +S to save them. (Fields
that you edit are highlighted blue until saved.)
• Administrators can disable Inline Editing if they need to.
• An additional dialog appears when you click on a Rich Text field like Description inline.
◦ If you want to add Images, Diagrams, or Attachment Previews to a Rich Text field, edit them in the
Work Item Editor.
(You can see Images and Diagrams when editing Rich Text fields inline, but you cannot Preview
them or edit Diagrams.)
• You can also edit the Table column inline.
◦ You can add content and rows to tables inline but must adjust column sizes in the Work Item Editor.
• The same goes with Test Steps.
◦ You can add content, rows and Test Parameters, inline but must adjust column sizes in the Work
Item Editor.
• Edit the field, click Done, but then click Save to save your changes.
Fields and cases where users cannot edit Work Item fields inline
• You cannot edit basic fields such as ID, Created, or Author in any view in Polarion.
• You cannot edit a custom field configured for a specific Work Item type, when the column also
appears in a query for other types.
• If users don't have the required permissions to edit fields.
• A field is configured as Read-only.
• A field is configured as a Calculated field.
• You cannot edit a custom field with a dependent enumeration. (Unless all dependent fields are
shown, and editable in the table.)
• If you are in Tree view and a Work Item is listed multiple times, to avoid conflicts, only the first
instance you click on is editable.
(Click beside the other instances to jump right to the editable instance.)
• Inline editing is disabled if you open the Prioritization or Approvals sidebars.
(Polarion prevents you from trying to open the sidebars, if you have unsaved inline edits.)
• Fields that are not listed in the table above can be edited by selecting the item and editing them in the
Work Item Editor that appears below.
• You cannot edit the Planned In field inline, but you can click the field in the Work Item table to access
the Planning sidebar.
Polarion knows when simultaneous edits to a Work Item conflict and informs you when it detects them.
Though the warnings vary depending on where you are editing from, they are all triggered by the
following scenarios:
• Another user edits and saves changes to a Work Item before you save new Inline or detail form edits
(but after you loaded the Work Item).
• Another user deleted a Work Item while you were working on it.
• You made and saved changes to the same item in another browser tab.
Tip
Conflicts refer only to edits made to the same fields. Changes to different fields/sections of a Work Item
are merged without a conflict warning. (See Resolve Conflicts for more information.)
If you change Work Item fields while Inline Editing, but another user (or yourself in another browser tab)
makes and saves changes to the same Work Item, you receive a conflict warning when you try to save.
(If up to two users made conflicting changes to the same Work Item, their name appears in the dialog. If
more than two users made concurrent changes, only the number of users appears.)
• You can view changes in the Work Item's History in a new tab before making a decision.
When you edit a Work Item in the Work Item Editor, but another user (or yourself in another browser
tab) made changes and saved the Work Item before you did, a warning also appears when you Save your
changes.
Click OK to overwrite the other user(s) changes or Cancel to cancel your updates.
The Bulk Edit feature enables you to select multiple Work Items and edit, move, or delete them as a unit.
When you save editing changes, values of modified fields are applied to all selected Work Items.
The set of Work Items available for editing varies according to the current Search query. You can use
Shortcuts or saved or custom Search queries to isolate or narrow the subset of Work Items you want to
edit all at once.
Caution
If you select one or more Work Items within a Derived Document, they are skipped if you try to Move
or Delete them.
Bulk Edit is available in the following views in the Work Items topic:
• Table
• Road Map
Procedure
1. Make sure you are working in the correct Project, and in the Work Items topic in that project.
4. In the Work Item Editor (lower half of the content pane in the Work Items topic) edit and change
field values as desired. (Some fields cannot be edited using Bulk Edit and are disabled. They need to
be changed individually.)
5. Click Save and Suspect or Save to save your changes and apply them to all the selected Work
Items.
The maximum number of Work Items that can be edited using normal Bulk Edit is set in the system
configuration. If more than the number set by the limit are selected, Restricted Bulk Edit is activated.
A panel of options appears and the word Restricted appears on the Bulk Edit button. You can edit field
values in this limited view, but the current values are not loaded in order to optimize server performance
for all users.
Warning
The number of Work Items you can modify via Bulk Edit is practically unlimited. Changing a large
number of Work Items places an unusual processing load on the server and also results in large
numbers of email notifications, with the resulting load on the SMTP server and the network.
The Description field is a rich text field that supports basic text formatting, images, tables, and hyperlinks.
When you edit the field, a toolbar displays above the text field and provides access to the formatting and
other features. The Description field is editable when the Work Item is in Edit mode. If the Work Item is
not in Edit mode, you can edit just the Description by clicking the Edit button.
• Where you can edit the Description field
• Format text
• Insert images or attachment previews
• Paste images from the clipboard
• Insert a table
• Insert hyperlinks
• Insert Diagrams
• Insert a Mathematical Formula
Description field-based Test Cases that use a table in the Description field as the source for the test
execution extension are affected by the merge command. If you Merge the cells of a test execution table,
the test execution extension does not work. Avoid merging cells in description based Test Cases.
See Compare table changes when cells have been merged for details on comparing historical changes
and how merging tables affects it.
• If you want to add, Images, Diagrams or Attachment previews the Description field edit it in the Work
Item Editor.
• You can also quickly edit the Description field inline in the Table and Tree Work Item tables.
• If you want to add Images, Diagrams, or Attachment previews edit them in the Work Item Editor.
(You can see Images and Diagrams when editing Description fields inline, but you cannot Preview
them or edit Diagrams.)
You can add tables inline but must adjust their column sizes in the Work Item Editor.
When you finish editing inline in the pop-up dialog (above), click Done, but then click Save to save
your changes.
Format text
The following text formatting features are available in the Description field:
• Bold font
• Italic font
• Underlined font
• Strike-thru font
• Superscript font
• Subscript font
• Text color
• Background color
• Remove formatting
• Outdent text
• Indent text
• Left-aligned text
• Centered text
• Right-aligned text
Text formatting features work in that same way as most word processors. For example, you can select
some text and apply some formatting to just the selected text. Or you can position the caret and select
formatting, and then everything that comes after has the specified formatting until you change it. The
toolbar also provides the Remove Formatting of Selected Text button, which removes all formatting
from selected text.
Note
• It is possible to configure Custom Fields with the same rich-text features as the Description field. For
information, see Implementing Rich-text Custom Fields
• Available fonts can be configured by an administrator.
• Background color is only available for text. Background color of table cells cannot currently be
formatted. Most browsers do not print text background color by default. If such printing is desired, it
may be necessary to change the browser's print options or settings.
You can display images or attachment previews in the Description field of Work Items. (Or any other rich
text field.). When you are focused on this field, the text formatting toolbar appears in the Work Item Editor
toolbar. It contains a button that enables you to select an image or attachment file and insert it in the
Work Item Description.
Caution
You can insert Scalable Vector Graphics (SVGs) into LiveDocs or rich text Work Item fields (like the
Description field), but you must also attach a .png file with the same name if you want to export
the Document to PDF or Microsoft Word. (If you don't, the following warning appears instead of your
image in the exported content.)
If you resize a diagram or SVG image in Polarionand change the aspect ratio, it is malformed when
exported to PDF.
After inserting an image or attachment preview, you can add a Caption above or below it, Resize it, or
launch a full screen Preview of it.
You can insert an image or an attachment preview a Work Item's Description or rich text fields.
With some limitations (see Note below), you can paste an image from your clipboard into a rich text field.
If there is a mixture of images and text in the clipboard, then only the name of the image file is pasted,
and not the image itself. When you paste an image, an attachment is automatically created with file name
screenshot-[timestamp].png, where [timestamp] is the date-time when the image was pasted.
Supported image formats are: BMP, JPG, PNG, and GIF.
To paste an image from your clipboard, simply locate the insert point where you want the image to appear
in the rich text field and use your browser's Paste keyboard shortcut or menu command.
Note
If you want users to be able to Copy/Paste and other editing functions for Work ItemDescriptions or
Documents, you must also grant them MODIFY CONTENT permission for Attachments when creating
a Custom Set. (Attachments are considered Work Item or Document content and are tightly tied to
Description permissions.)
Insert a table
When the Description field is in Edit mode, the button provides a menu with options for inserting and
managing a table in the field. If the caret is not currently placed in a table, only the Insert Table command
is available. All other commands are available when the caret is inside a table. When a table exists, you
can:
2. Click on the toolbar and choose Insert Table from the menu. The Insert Table dialog box
appears.
After inserting a table, click inside any cell to enter text. All of the Description field's text formatting
options are available for text in table cells.
You can also insert images in cells in the same way as described in insert images.
Table columns are self-sizing. You will notice some variation as you enter content in cells. Just enter your
content in the cells, and the end result should look okay. If necessary you can increase or decrease the
width of the table in Table Properties.
Note
The maximum width of tables is 1280px when the width is configured as a percentage value. If the
width of a table is configured in pixels, then there is no limit.
• Another table
• Work Items or Headings
Tip
Hold Shift and right-click to override the table's context menu to paste via the browsers context menu.
To unmerge previously merged cells, click on a merged cell, and then right-click and select Unmerge.
Insert hyperlinks
You can insert hyperlinks in the Description field of Work Items using the Insert Link button on the Work
Item Editor toolbar when the Work Item is in Edit mode. Links are local to the Work Item. That is, you can
only create links to things that are linked to the Work Item:
Depending on the configuration of, and current selection in the interface list (in the Tool view of
Navigation), these resources may not appear in the Work Item Editor for some users. Placing a hyperlink
in the description provides exposure in the Work Item Description (always visible) of potentially hidden
linked resources.
If a GitLab repository is configured and the fields below are added to the Work Item Form (Editor)
layout, GitLab merge requests can be done within a Polarion Work Item.
Procedure
1. Before creating a merge request within a configured Work Item, you should have already created
your branch in GitLab, committed the changes to your local branch and uploaded the local repository
content to a remote repositoty using git command line or GUI software.
a. Navigate to the local Git branch that you're working on.
b. Add, remove, or edit files and then save the changes.
c. (Optional) Type git status to see what files have changed.
Tip
The Copy ID + Title command makes for a great commit message.
Note
The Create Merge Request button will only be visible if the "sourceBranchNameField="
points to an existing custom field on the editor and if that field contains a value.
6. (Optional) Scroll down to the bottom and click Commits or Changes to review the changes.
7. Click Submit merge request.
8. You are redirected to the merge request's details screen.
(Whether your merge request requires an approval or is merged automatically depends on how your
administrator configured GitLab.)
9. If you refresh the Polarion Work Item, the new merge request appears in the Merge Request section.
Any GitLab merge request related to the branch specified in the sourceBranchNameField custom field
appears in the Merge Request section of the Work Item.
The Assignee field is a drop-down list of Polarion users (filtered according to permissions).
You assign a Work Item to a person with the Assignee field on the Work Item detail form or inline in the
Work Item table.
Tip
• To assign the same people to multiple Work Items, Select all of the Work Items and Bulk Edit your
Assignees in the Work Item detail form.
• To quickly assign different people to multiple Work Items, edit Assignees inline in the Work Item
table.
Note
The Assignee must have an account in Polarion and be assigned the assignable role to appear in the
Assignee list.
You can assign the same Work Item to multiple people. For example, you might have a "Meeting" type
Work Item and you want to track the time spent by all participants who attend.
• Select the first Assignee, then click and select someone else from the drop-down list.
• Click beside an Assignee to remove them.
• To unassign an item completely, select -- from the drop-down list.
• Any Assignee who spends time on a Work Item can create a Work Record to report the time they spent
on it.
The Status field is where you move a Work Item through its configured workflow.
You can change the Status of a Work Item directly in the Work Item Editor without entering Edit mode or
directly in the Table and Tree Work Item tables.
When you select a new value in the Status field, you enable the Save and Cancel buttons.
(Depending on the workflow configuration, you may be able to view and/or edit other fields such as
Resolution.)
Tip
If the Status you want to select is grayed out, hover over it for a tooltip explaining why.
Here's a few things to know when you edit the Status field in Table and Tree Work Item tables:
• If the Workflow configuration specifies that a field must be Cleared, it is cleared even if it is not rendered
in the table.
(You can check the Work Item's History to see what was removed.)
• If a field is set to be Cleared when the Status changes (but was not saved yet), then the field is not
editable in table views, and the following tooltip appears:
You can edit the field again after the Status change is saved. (Unless configured otherwise.)
• If a Required field rendered in the table has a validation error, it's highlighted in the table.
• If a Required field is NOT rendered in table view, you can add a value from the Status' dropdown menu.
• If you trigger a validation error while changing the Status in the table, its row's background switches to
a gradient, and you cannot save your changes.
When you must change the Status in the Work Item Editor
• Even if Comments are a Required field, you cannot change the Status via table views because you
can only add Comments in the Work Item Editor.
• If a Status change requires an electronic signature, you must change it in the Work Item Editor.
Scenarios that affect whether you can change the Status anywhere
• All dependent Required fields must be visible as columns if you want to change the Status in table
views, but you can also just add their values in the Work Item Editor.
• You must satisfy all configured Workflow Conditions to change the Status both inline or via the Work
Item Editor.
• If the required Role for the workflow change is not met you cannot change the Status inline or via the
Work Item Editor.
The Status drop-down shows only transitions permitted by the workflow configuration, based on the
item's current status. For example, the workflow configuration might require an item with status Open to
transition to a status Verified before the Close action appears in the Status field's drop-down allowing the
item to transition to the Closed status.
Tip
Your project leader or administration should familiarize the team with the workflow configuration so
that every understands the different Work Item Statuses and the actions available in each Status. In
general, the workflow configuration maps the team's process and prevents steps from being skipped or
bypassed.
• Direct links: When you use a link role Name like relates to you create a Direct link in a child Work
Item.
(You can link individual Work Items, Multiple Work Items at once, or Work Items on remote Polarion
servers.)
• Derived links: When a Direct link is viewed from the parent Work Item it's referred to as a Derived link
(Or backlink).
You can also create this link from the parent Work Item using the opposite is related to role.
(This link is stored as a Direct link in the child Work Item.)
Tip
◦ You can learn more about the default types of Work Item link roles in configure Work Item
linking.
◦ You can limit the number of Work Item links that appear in Work Item titles, and other places for
increased performance and usability.
• Suspect Links: The Suspect flag alerts the owners of linked Work Items of a change that might
also affect their items.
• Link to Revisions: You can link your commits to local or external repositories to Work Items.
They then appear as linked revisions in the Work Item Editor.
/**
* {@wi.implements elibrary_alm/EL-122 messages can take up
* several lines in the code. Just surround the whole parsing syntax
* with {}
* Anything commented after will not be included.
*/
Traceability
Linking Work Items is how you take advantage of the Traceability and Impact Analysis features. Even
though these may not be available to everyone on your team (depending on licensing), you should plan
and follow a process of linking Work Items from the outset, as it will be important for those users who do
have access to traceability and impact analysis.
You want to create links from items like requirements to do the following:
By doing this, your team will have several key advantages with Polarion. You will be able to:
• Trace from requirements to the Work Items and the source code that implements them
• Back-trace from some defective code (in a repository revision) to the tasks/change requests that
implemented the defective code, and from those to the requirement that called for the functionality.
• Assess the impact (and by extension, the cost) of a changed requirement by viewing all the artifacts
affected by the change.
• Review and analyze various relationships between Work Items such as dependency, relevance, parent-
child, duplication, and follow-up.
It is also possible to link Work Items while working in a Document. This is covered along with topics on
working with Documents. See Link a Document's Work Items.
In the Work Item Editor, you can link Work Items located on a remote Polarion server, specific
revisions, (on the default SVN or external repositories), your source code, and more.
Tip
See Link types and terms for details.
Procedure
4. Select a link Role then click type of Work Item that you want to link.
• (Optional) Click to select a Work Item from the same Polarion server via the Work Item Picker
dialog box.
Tip
Click to refine your search or redefine the scope in the drop-down on the right.
Tip
• Select Don't show this again to remove the Confirm Save dialog box on future saves.
• Click on the right of linked Work Items to remove them.
The technique using the Bulk Edit feature is the same as for single Work Items. The same sections exist in
the editor.
You can link a Work Item to a specific revision in the default SVN repository or to configured external
repositories.
Tip
• You can also link to a specific revision of another Work Item.
• Linked Revisions can also be configured so that they appear in the Work Item Properties sidebar.
• You can link a resolved item to a Repository revision or even Auto-link via Subversion commit
messages.
Procedure
1. Select a Work Item in Tree or Table view or click on it in a Document and click the Open Item
menu option.
5. (Optional) If you do not see the revision you want to link, expand the scope under the drop-down
fields and click Search.
(It lists only the current user's revisions by default.)
Tip
• Are revisions located on the local SVN repository.
You can also link to a specific revision of another Work Item under the Linked Work Items section.
Procedure
1. Select a Work Item in Tree or Table view or click on it in a Document and click the Open Item
menu option.
• Head: The link always points to the HEAD/newest revision. (No revision number is set in the link.)
• Current: The link points to the revision that was the HEAD revision when the link was added.
• Specific: Enter the specific revision number you want to point to.
If you select Specific, an additional field appears and you must click and select a revision
number from the Revision Picker.
Note
• If you follow the link to the Linked Work Item, you cannot see the link back to the original Work
Item in the linked revision.
(When you follow the link, you see the Work Item as it appeared in that revision, including the
links and backlinks it had before the incoming link existed.)
• If you want to see and maintain bidirectional links across history and baselines, consider using
Collections.
When focused on any Work Item in the Work Item Editor, you can quickly create a new Work Item and a
link in a single operation. You can create two basic link types this way, each having several possible link
relationships:
• Linking Work Item: Create a new Work Item and an incoming link to the current item from the new
item.
• Linked Work Item: Create a new Work Item and an outgoing link from the current item to the new
item.
In the default project configurations in project templates, a new Linking Work Item can have any one of
the following relationships to the current Work Item:
Procedure
1. In the Work Item browser, select the Work Item that you want to create a new Linking Work Item
for.
2. Create a Linking Work Item by doing one of the following:
(If you click above the Work Item you create a Linked Work Item).
Choose the type and the link relationship for the new Work Item you want to create.
In the default project configurations in project templates, a new Linked Work Item can have any one of
these relationships to the current Work Item:
Procedure
1. In the Work Item browser, select the Work Item that you want to create a new Linking Work Item for.
2. Create a Linked Work Item by doing one of the following:
(If you click below the Work Item you create a Linking Work Item).
Choose the type and the link relationship for the new Work Item you want to create.
Tip
Linking Work Items is vital for creating traceability. See the Link types and terms, section for details.
Common linking scenarios include:
You can quickly add a link to an existing Work Item by doing the following:
Prerequisites
Make sure that Linking Menu and Linked Menu are configured in the Form Menus configuration, see
Configure Work Item linking menus.
Procedure
1. Open the Work Item that you want to add a link to.
2. Do one of the following:
• Click the plus icon in the header above the title to add a linking item, or the icon below the
title to add a linked item.
• Click the icon and choose Add Linked Work Item or Add Linking Work Item.
3. Choose one of the items configured to link an existing item to the Work Item.
The Work Item Picker dialog is displayed. The query and scope of the Work Item Picker depends on
the configuration of the Form Menus administration page.
4. Select the desired Work Item to be linked.
Note
You can add multiple existing Work Items at once. Simply select the check boxes of the
corresponding items you want to add.
The Work Item is displayed in the Linked Work Items section of the Work Item Editor.
5. Click Save.
To create Work Items with links to Work Items from another Polarion project, add the Project ID from
the other Polarion project to the front of each Work Item in their respective Excel cells. (ProjectId/
WorkitemId).
Use Quick-link
You can quickly link a selected item in the table to one or more other items in the table using the
Quick-link feature. Click on the row of the Work Item you want to link. The target item or items must
also appear in the table. You might need to modify the search query to retrieve all the items to be linked.
Procedure
1. Select an item in the Work Items Table and click on the item's row. The Link Detail dialog box
appears.
2. In the Link Detail dialog box, select the link role for the link you are creating. This describes the
relationship of the source item to the target item(s) (Relates to or Depends on, for example).
3. If you want to link to multiple other Work Items, hold Ctrl (Windows) or Command (Mac and
others).
4. In the table, locate the first Work Item you are linking to, and click the left of it. If you are linking
to multiple items, scroll the table as necessary to locate each target item and click on it, continuing to
hold down Ctrl or Command during the operation. The Link Detail dialog box updates with each link
added.
5. You can save the links in two ways:
• To save a single link just click in the Link Detail dialog box.
• If linking to multiple items, click in the Link Detail dialog box then
(Links are not saved in the repository or theView Work Item History until you save.)
Tip
After initiating a link, if you then create a new Work Item, the new item will be linked to the first with
the role selected in the link detail panel when you save the new Work Item.
If you make a mistake selecting a target item, you can click X in the link detail panel, confirm the cancel
changes, and begin the linking process again.
You can open source Work Items in one browser tab/window and target Work Items in a different
tab/window. Start the link with an item in the first, and finish by clicking link icons of one or more items
in the second tab/window. The tabs/windows can contain either a Document or the Work Items Table.
The icon for initiating a link is also available in the Edit a Work Item, to the left of the Work Item's
title.
For information on linking Work Items to repository revisions, please see: Linking a Resolved Item to a
Repository Revision.
Tip
You can use Work Item Actions to create individual linked Work Items.
If your installation has multiple Polarion servers in a clustered environment, and if any of those servers
hosts its own Polarion repository, you can link to any Work Item in the repository of one server to another
Work Item hosted on a different Polarion server. Work items on the other server are called Remote Work
Items. To create a link to a Remote Work Item, you must know the URL of the item on the other server.
If you don't already know it, you must log on to the other server, search for the target Work Item, select
it, note its URL, then log back onto the first server, and proceed to link your Work Item to the one on the
remote instance.
Once you know the URL of the remote Work Item, the procedure to link to the remote item is
straightforward:
Procedure
1. Navigate to and select the Work Item that you want to link to a remote Work Item from.
2. Scroll to the Linked Work Items section of the form. The last line in this section is ready for you to
specify a new link.
3. In the Title column, click the icon. A browser prompt box appears.
4. Enter the URL of the target Work Item on the remote host, and click OK.
What to do next
Tip
Remote Work Items appear in the same Linked Work Items table as locally hosted items, but they
display the remote server icon in the Project column.
You can link the Work Items defined in a Document to other items in the same Document, in a
different Document, or stored directly in the Tracker. Links can denote structure and provide traceability.
For example, in a requirements specification Document, Requirement Work Items may be structured
with parent-child relationships where one item is the parent of one or more others. This type of structure is
most easily and naturally done with hierarchical headings and/or indentation — of paragraphs or list items,
for example. For information, see Structure a Document's Work Items.
Linking for traceability may require linking Work Items defined in one Document to Work Items defined in
a different Document, or created directly in the integrated Tracker. For example, you would probably want
to link Requirement Work Items defined in a requirements specification Document, to Test Case
items that verify the requirements. The Test Cases might be defined in another section of the same
Document, in another Document, or created directly in the Tracker. For more complete information, see
Link Work Items.
The following sections explain how to link Work Items to each other in the same Document, how to
link Work Items in one Document to items in a different Document, and how to link Work Items in a
Document to Work Items created directly in the Tracker.
Tip
No links are created in the system until you save the Document in which you originate the link(s). If you
accidentally create a pending link to the wrong target item, you can click the X icon in the link detail
panel and then confirm the prompt to cancel changes. You can then begin the linking operation again.
When linking to multiple Work Items, you can specify a different link role for different target items. For
example, you might link from a Requirement to a Test Case with a link role named Verifies,
and to another requirement with one named Refines. You select the link role in the Link Detailpanel
after clicking the link icon on each target Work Item.
You can link one Work Item in a Document to another single item, or several target Work Items in the
same Document all at once. For this operation, you only need one browser tab.
Procedure
1. Click on the icon in the left margin of the Work Item you want to link to some other Work Item.
The link detail panel appears.
2. In the link detail panel, select the link role for the link you are creating. This describes the relationship
of the source item to the target item(s) — relates to or depends on, for example.
3. Locate the first Work Item you are linking to, and click to the left of it.
If you want to link to multiple Work Items, hold down Ctrl (Windows) or Command (Mac and
others), and click the (Create Link) icon of each target Work Item. The panel reports the items
linked each time you click.
4. Save the Document. The links are not created in the repository or logged to the Document History
until you save.
You can link a Work Item in one Document to another single item in a different Document, or to several
target Work Items in a different Document all at once.
Tip
This linking is easiest if you open 2 browser tabs or windows: one displaying the Document containing
the Work Item(s) you want to link (referred to as Tab 1), and the other (Tab 2) displaying the Document
or Tracker view containing the Work Item(s) you want to link to.
Procedure
1. In one browser tab or window (Tab 1), open the Document containing the Work Item(s) you want to
link.
2. In a second browser tab or window (Tab 2), open the Document containing the target Work Item(s).
That is, the item(s) you want to link to from some item(s) contained in the first Document (in Tab 1).
3. In Tab 1, select a Work Item to link by clicking on the (Create Link) icon in the item's left margin.
The link detail panel appears in both browser instances.
4. In the link detail panel, select the link role for the link you are creating. This describes the relationship
of the source item to the target item(s)— Relates to or Depends on, for example.
5. Switch to Tab 2. If you want to link the item in Tab 1 to multiple items in Tab 2, press and hold Ctrl or
Command (depending on your operating system).
6. Click the (Create Link) icon beside the first target Work Item in Tab 2. To link to one or more
additional items in this target Document, click their link icons while continuing to hold down the Ctrl
or Command key.
7. Switch back to Tab 1 and save that Document (the one from which you started the link operation) to
create the links in the repository and Document history.
Tip
You can link new Work Items in a target Document as you create them. When you begin a link from
a Work Item in one Document (in Tab 1), then if you switch to a different Document (in Tab 2), and
you create new Work Items there, links to the new items are automatically created and added in the link
detail panel.
Tip
You can link a Work Item to one or more items in a historical revision of a target Document. For
example, you might link the current revision of a Business Case item to the version of a Requirement
in a functional specification Document that has been saved in a Project Baseline. To do this, open
in Tab 2 the Project Baseline containing the revision of the Document, and then open the Document
containing the items you want to link to.
You can link a Work Item contained in a Document to one or more Work Items created in the Tracker that
are not contained in any Document. You can link to a single target item, or multiple target items at once.
As in the previous section, you should use 2 browser tabs.
Procedure
1. In one browser tab (Tab 1), open the Document containing the Work Item(s) you want to link.
2. In a second browser tab (Tab 2), open the Table view (Navigation Work Items), and run a
query to retrieve the target Work Item(s) and list them in the table.
3. In Tab 1, select a Work Item to link by clicking the in the item's left margin. The link detail panel
appears in both browser instances.
4. Select the link role for the link you are creating. This describes the relationship of the source item to
the target item(s)— relates to or depends on, for example.
5. Switch to Tab 2. If you want to link the item in Tab 1 to multiple items in Tab 2, press and hold Ctrl or
Command (depending on your operating system).
6. In the table in Tab 2, locate the first target Work Item and click the on its row in the table. To link
to one or more additional items in the table, click the link icon on their respective table rows while
continuing to hold down the Ctrl or Command key.
Note
Each target item can be linked with a different link role. Change the role in the link detail panel
after Ctrl / Command clicking an item.
7. Switch back to Tab 1 and save the Document to create the links in the repository and Document
history.
Tip
You can link Work Items using other tools in the Polarionportal. You can use the Linked Work Items
section in the Work Item Editor (Navigation Work Items Table view). If your license
provides the feature, you can also link Work Items in the Matrix view.
See also:
Use the Edit Links button in the Properties page of the Document sidebar to launch the Linked Work
Items dialog box. There, you can manage the links of the currently selected Work Item in your Document.
You can use the dialog box as an alternate way to add one or more links to a selected Work Item, as well
as to edit some properties of existing links, or remove some existing links. For details about this dialog,
please see Linked Work Items Dialog
Polarion supports externally Linked Data that lets users link to objects from other tools, like Teamcenter.
• Create links for or LiveDocs from objects that reside on external, Linked Data enabled tools. (Act as a
Linked Data consumer.)
• Link Polarion Work Items to objects that reside on external, Linked Data enabled tools. (Act as Linked
Data provider.)
(This is generally done by creating or selecting a remote object in a delegated UI provided by the Linked
Data provider.)
Once Linked Data Friends are configured by an administrator, they appear as an icon in the
Linked Work Items section of a Work Item.
Tip
They also appear in the Links section of the Work Item Properties sidebar.
Procedure
5. Click on the blue Linked Work Items masthead or to edit the section.
6. If you have associated a Linked Data artifact container with the current project, you will see an
icon.
9. Select the External Linked Data location from the Location drop-down box.
10. Click Select an Existing Item. (Or Create New Item to create a new item within the external
application.)
Note
Create New Item will launch the external Linked Data application in a pop-up window.
(The workflow to create a new Item will vary depending on the application.)
b. Select an item from the list on the left. (An overview of its details appears on the right.)
c. Click OK. The item is linked to the Polarion Work Item.
d. Hover over the link to get a preview of the linked object.
* Mouseover preview
12. Do the following:
a. A new Work Item from an External Polarionserver:
Select a Polarion Server from the Location drop-down box and click Create New Item...
d. Enter the required fields and click Create. The Work Item is created and linked to the local
Work Item.
e. Hover over the link to get a preview of the linked Work Item.
13. Click Save. (Links are created on both the local and external applications.)
If there is a connectivity issue while adding or removing Linked Data links, the following error appears.
Suspect links
The Suspect flag alerts the owners of linked Work Items of a change that might also affect their items.
(It appears on Work Item child links if their parent item is updated.)
Note
• The Suspect flag is not applied to structural Work Item links.
• Suspect warnings are applied to all Work Items that link to the item being changed in their HEAD
revision.
(Work Items outside a Collection get a Suspect link, even though they are not displayed in the
parent Work Item.)
You can turn the suspect attribute on and off using the Suspect check box beside each linked Work Item
in the Linked Work Item section of the Work Item Editor.
You can toggle the Auto-Suspect option using the Auto suspect control in the Document Properties of
the Document Sidebar (for Document-based Work Items).
How the Suspect flag is configured, triggered and applied to Linked Work Items
• Administrators can configure whether Suspect flag is enabled automatically by default on a project
or global level.
(See Suspect default state for details.)
• You can also apply it to any Work Item by selecting Save and Suspect when saving changes to a
Work Item.
• If you want all Work Items in a Document to display the Suspect flag when modified, then you can
switch Auto-Suspect to ON in the Document Properties sidebar.
Note
The Suspect attribute is only applied if Work Items are modified within the Document and is only
applied to child Work Item links.
(Not to Parent or structural links within a Document.)
• The Auto-Suspect attribute controls the Suspect flag for the links to all child Work Items.
(This includes links to derived Work Items but excludes structural Document links.)
In the example below, a Requirement (DOCU-473) was added to the document, positioned as a child
(using “Tab”), and linked to DOCU-461 using the is refined by option. The document was then Saved.
Structural links and their relationships are visible directly within the document and should be updated
along with the parent.
Below is a child structural Document that WILL NOT be subject to Suspect warnings:
The Description in the DOCU-461 Requirement Work Item was changed, and then saved using Save
and Suspect.
All the external child links for DOCU-461 are marked as Suspect, but the newly created structural
childlink DOCU-473 is not.
Resource Traceability lets you add a comment in your source code so that a link appears under the
Linked Resources section of the configured Work Item(s) they reference.
If administrators
set the View
Traceable
Resource Local
URL. (
Administration
Repository )
Comment syntax
Tip
• See Link a resource for multiline message examples, a list of supported elements, and where you
should place the comment in your code.
• Search strings can also be defined that only search for Work Items with or without Linked
Resources.
The Matrix view provides a robust way to both create and browse links. The matrix is populated with
two subsets of Work Items - one for matrix rows, and one for columns. Each subset is built with a query
in the special dual version of the Query builder. Each query can access either Work Items or repository
When the matrix has been populated, the intersection of each row and column shows if there is an
existing link between the items in that row/column, and provides the possibility to create one if none
currently exists. Existing links show an arrow in the intersection indicating the direction of the link.
Clicking on the intersection pops up details about the link.
Procedure
1. Populate the rows and columns of the matrix by building queries that will display the source and
target Work Items (or Work Items and repository revisions) in the matrix rows and columns.
Tip
If you filter Work Items for one type in Navigation you may not get the query results you expect in
the Matrix. You should generally select the top-level Work Items node in Navigation rather than
one of the Work Item types listed in the sub-nodes.
Tip
You can do this step either before or after creating the link in the Matrix (see next step).
5. Locate the intersection of the Work Items you want to link (or the Work Item and the repository
revision you want to link, and click on that cell. A green arrow appears in the cell showing the
directionality of the link. The actual link is not yet created.
6. Click Save to create the link. The green arrow in the cell changes to black.
The Hyperlinks section the Edit a Work Item provides a means to link a Work Item to any kind of
online resource via a URL. For example, you might link to relevant Wiki pages or Documents,
or to repository folders and files in your Polarionportal, or to pertinent information on the web or your
organization's intranet. When creating a hyperlink to any resource, you can specify whether it is an internal
or external resource.
Hyperlinks are supplemental to the traceability links you create between Work Items. For traceability, you
should always link Work Items to each other with an appropriate link role, and not use the Hyperlinks
feature. Hyperlinks are disregarded by analysis features such as Traceability and Impact Analysis. If you
want Work Items and Revisions to be available for analysis processes, do not use hyperlinks to link them
as generic URLs.
Tip
Hyperlinks can also be configured so that they appear in the Work Item Properties sidebar.
Usage Examples
Example 1: For a Task Work Item that requires the delivery of a document stored in the Subversion
repository. (Not kept as an attachment to this Work Item, but resides in another other location).
You can create a hyperlink to the actual document once it is created. For example: http://
myserver.company.com/repos/documents/text.doc.
Example 2: Link to any resource on the Internet. For example, link to Internet pages that are relevant
to topics discussed in comments, so that everybody can easily refer to them. So a comment might
say something like "this feature should be essentially like Their Product's Foo Bar functionality". Then
Example 3: Link to some resource in your Polarionrepository and open it in the Repository Browser,
for example, http://polarionhost.company.com/polarion/repo/someFolder leads to the
Repository Browser's info view of the specified folder. Any hyperlink URL that appears to be a repository
URL (starting with values specified in the system configuration property repo or repo.ui) is rendered as
a repository URL and the link opens in the Repository Browser tool.
Hyperlink roles
Hyperlink Roles are meant to help categorize hyperlinks, something like the Title for attachments.
Currently Polarion does not rely on them in any way. Roles are completely configurable in the The intent
behind the default configuration is that refers internally is for links to the Subversion repository, while
refers externally is for linking to the Internet or systems outside Polarion/SVN. Hyperlink Role is really just
a label.
Hyperlink Roles are meant to help categorize and label hyperlinks, something like the Title for
attachments. Currently Polarion does not rely on them in any way. Roles are completely configurable
in the Administration interface ( Work Items Enumerations hyperlink-roles-enum).
Hyperlink types
Create a Hyperlink
You can create a hyperlink in the Work Item Editor when the Work Item is in edit mode or by clicking the
Edit button in the Hyperlinks section when the item is in View mode.
The user interface presents combo box controls for setting the role and the type.
When hyperlinking to an online/external resource, select URL in the Type field and enter the URL in the text
box to the right of the combo box.
When hyperlinking to a Subversion URL, select Repository URL in the Type field. The (Select Repository
URL) icon appears at the right side of the URL text box. Click this icon to display a picker dialog in which
you can browse the repository, and select the URL you want as the hyperlink target. The selected URL
appears in the URL text box.
Approval Center
Polarion supports a formal approval process for any type of Work Item through the Approval
Center feature. The preconfigured project templates delivered beginning with version 2013-SR1 have
preconfigured support for approvals.
The out-of-box approvals support delivers several features and capabilities for organizations that need a
formal approval process with an audit trail.
• Workflow Integration: Approvals are integrated into the workflow of Work Items, including all types of
requirements. Approvals can be added to the workflow of any Work Item type that does not already have
it, including your own custom types. Integrating approvals into the workflow ensures that steps and
people are not skipped or bypassed in the approval process.
Workflow also automates some tasks, such as designating users as Approvers and notifying them to
review and approve items. For example, when a Work Item transitions from an initial draft status to a
ready for approval status, a specific list of users, and/or all users whose user profile includes a certain
role can be automatically designated as Approvers. These users' names are added to the Approving
Users list in the Approvals field of the Work Item, and email notifications are sent to them.
• History and Audit Trail: An automatic, reportable history of the approval process is automatically
maintained, so it is always be possible to find out who approved what and when.
• Easy for Approvers: The Approval Center is designed to facilitate users who are designated to review and
approve or disapprove items:
◦ Links in email notifications lead users directly to items they should review and approve or disapprove.
◦ The portal user interface makes it fast and simple for any user to access the items awaiting his/her
approval.
◦ Approvers can approve or disapprove multiple items at once in a single operation.
◦ Approvers can discuss items with other stakeholders in threaded Approval Comments.
◦ Approvers can choose to work in a document interface (assuming the items are contained in a
LiveDoc Document) or in the Tracker tool.
◦ Organizations can obtain inexpensive Reviewer licenses for use by people whose only role in projects
is to review and approve Work Items. The Reviewer license also enables users to review and approve
Work Items on Apple iOS mobile devices using Polarion's ALM2GO app.
• Easy for Managers: The Approval Center also helps project managers, team leaders, and others to track
and manage the approval process:
◦ Easily review, respond to, and resolve Approval Comments, as well as create new Approval
Comments.
◦ Hide or reveal resolved Approval Comments.
◦ Explicitly invite users to review and approve items via email or instant message.
◦ Quickly review the current state of the approval process for any item in real time.
◦ Reopen approvals for revised items that were disapproved, removing the disapproval state and
starting the review and approval process again.
Before starting to use the Approval Center feature, there are some preliminary issues with which you
should become familiar:
• Roles and permissions: Important for project leaders and administrators. Make sure that all users
responsible for reviewing and approving Work Items have the necessary role assignments with the
necessary permissions.
• Workflow Configuration: Important for administrators and project leaders. Others may find the
information useful to better understand underlying concepts, but it is not essential in order to find
and approve the Work Items you are responsible for reviewing.
• Approvals Interface: Important for everyone involved in the approval process. You need to familiarize
yourself with approvals-related user interface features in order to find, review, and approve/disapprove
the items for which you are designated as an Approver.
• Require a signature when approving a Work Item: Polarion can be configured so that a Work Item's
workflow status and the item itself require an electronic signature to complete the approval process.
There are several user permissions that provide security for approvals.
Approve Work Items: To be able to approve Work Items, users must be assigned the project
role project_approver, and this role should be granted the permission named Permission to
APPROVE/DISAPPROVE.
Approve as Different User: To allow users to mark items as approved or disapproved by another user (that
is a different user other than themselves), an administrator can grant the Work Item permission named
Permission to APPROVE/DISAPPROVE as ANOTHER USER.
Resolve Approval Comments: To be able to resolve Approval Comments, users must be granted
Permission to RESOLVE COMMENTS.
Your approach here depends on whether you need to run an approval phase for a new project, or in an
existing project where approvals are not configured into the workflow.
For new projects, it is recommended to create them using one of the project templates delivered with
Polarion version 2013-SR1 (or later). Workflow in these templates is preconfigured to support a formal
approval process. After creating the project, you should review the workflow for each Work Item type and
make sure it is okay with your process. In particular, review the Actions section of the Workflow Designer
page, looking at the Actions on each row in the table (see links below).
Polarion's project templates are designed to meet the needs of a wide variety or organizations. However, if
the default workflow, including workflow statuses and actions, do not meet the needs of your project you
either need to create a custom version of one of the stock project templates, or customize the workflows of
the specific project. In this case, see these topics:
• Configure Work Item Workflow (See this topic if you find you need to customize any part of your
project's workflow. In particular, see the subtopic Workflow for Approvals.)
• Customize Project Templates (See this topic if you find you need to customize your project's workflow,
and the same customization is needed for all or many other projects.)
If you have an existing project created from a project template prior to Polarion version 2013-SR1, and that
project still needs to go through a formal process of approval of requirements or other types of Work Items,
you may want to customize your project's workflow to include or better support approvals by using the
Approval Center feature.
The easiest approach is to create a sandbox project based on one of the new project templates, and in
that project review the workflow configuration. You can then duplicate that configuration in your existing
project. Be sure to edit the Actions and check for workflow conditions and functions, incorporating them
"as-is", or tweaking them in your existing project. See Workflow Functions and Configure Work Item
Workflow, especially the subtopic Workflow for Approvals.
Electronic Signatures
In some industries you must meet strict regulatory requirements for traceability and be able to document
when requirements were approved and by whom, ensuring that only authorized people can "sign off"
on them. Your administrator can configure Polarion to support electronic approval signature that will
satisfy many regulatory requirements in many industries. Be sure to check that electronic signatures for
requirements approval are allowed by the body whose regulations you must meet. For information, see
Require Signatures for Workflow Actions.
Note
If a Work Item that has been approved using an electronic signature is duplicated, the new Work Item
does not show any indication of the source item's signature, and the new item is not approved or
electronically signed. New duplicate items must be reviewed, approved, and e-signed.
The main user interface component for reviewing and approving Work Items is the Approvals sidebar. In
a Document, it is one of the sidebars available in the Document Sidebar. You can show and hide it with
the Sidebar menu in the Document Editor toolbar. In the Table or Tree view of the Work Item Tracker, you
can find it on the sidebars menu, on the toolbar next to the Query Builder. Refer to the following figure to
locate the access control:
Note
Inline editing is disabled if you open the Approvals sidebar.
• All Approvals: Reports statistics of the current state of all Work Items, regardless of who is designated
as Approver(s). Also enables you to invite people to approve Work Items by providing a URL which
you can paste into email or instant messages. When a Work Item is selected, this tab also provides a
button for adding an Approval Comment, displays the names of users who are assigned to approve,
have approved, and have disapproved the current item, and displays all Approval Comments for the
Work Item, if any.
• My Approvals: Reports statistics of all Work Items for which you are designated as an Approver. When
a Work Item is selected, this tab also provides buttons for approving or disapproving the current item,
provides another button for adding an Approval Comment to the item, displays the names of other users
who are assigned as Approvers of the current item and what action each of those users has taken, and
displays all Approval Comments for the Work Item, if any.
No selection N
o
s
e
l
e
c
t
i
o
n
Approval statistics are color coded in the user interface (see previous figure).
• Outstanding - All Approvals: No user is currently designated as Approver. My Approvals: You are not
currently designated as Approver.
• Waiting - All Approvals: Waiting for approval by at least one user and no user has disapproved it. My
Approvals: You are designated as an Approver, and the reported number of items are waiting for you to
review and approve them.
• Approved - All Approvals: The item is approved by all the currently designated Approvers. My Approvals:
You are designated as an Approver, and you have approved the item.
• Disapproved - All Approvals: The item is disapproved by at least one of the currently designated
Approvers. It is reported as Disapproved until such time as the disapproval is resolved, even if one or
more Approvers have approved it.
My Approvals: You are designated as an Approver, and you have disapproved the item.
The Approvals sidebar statistics are for the current context such as Document or project.
Approvers are normally designated automatically by the workflow engine on the basis of some role
('project_approver', for example), or an explicit list specified in the workflow configuration. The list of
designated Approvers appears in the Approvers field of a Work Item when viewed in the Table view. It is
possible to add Approvers to the list manually.
The topics in this section focus on tasks involved in the default approval process (as configured in Polarion's
project templates), and explain how to access and use the relevant Approval Center features. Unless
specifically noted otherwise, the information pertains to Work Items contained in a LiveDoc document and
to Work Items contained in the Work Item Tracker (Navigation Work Items).
Procedure
1. Open the Approvals panel for the context you want to review (Document or project tracker), and
select the All Approvals tab.
2. If reviewing in a Document, do not select any Work Item. If reviewing Document-based items in the
Table or Tree view of the Tracker, select any Heading item.
The Approvals panel shows a statistics summarizing the overall status of approvals, reporting counts for
items Outstanding, Waiting, Approved, and Disapproved. See Understand the Approval Statistics for
more information.
If Work Items are not contained the Work Item Tracker, one Work Item is always selected, so you cannot see
the Approval in its state when no item is selected. You can, however, still see the overall approval statistics
in the Approvals panel.
Invite Approvers
Approvers designated for a Work Item are listed in the Approving Users table of the Approvers field of
Work Items. You can view the list in the Table or Tree view of Work Items. Ideally, Approvers should be
automatically designated via the workflow. It is also possible to add Approvers by manually editing the
Approvals field. Either way, when a user is designated as an Approver the system automatically sends
him/her an email notification.
In an ideal world, all Approvers respond to the automated email notification and log on to review the
Work Items they must approve. However, in reality, many people set up rules in their email clients that
file or even ignore Polarion-generated notification emails, or they simply don't read notification emails. For
Procedure
1. Open a Document containing the Work Items that are ready for approval review, or open the Work
Items topic of a project containing tracker-based Work Items that are ready for approval review.
2. Open the Approvals panel and select the All Approvals tab.
3. Click Invite for Approval.
4. In the Invite for Approval dialog box, copy the URL displayed there to your computer's clipboard.
5. Create email messages or instant messages for people who must review and approve the Work Items,
pasting the URL from your clipboard into the message body along with any other text you write. For
example, you might provide explicit instructions for your approval process in addition to the link.
If your job is to review and approve Work Items, the Approval Center feature provides an easy way to locate
the items you need to review to approve or disapprove.
Procedure
1. Log on to your Polarion portal and open the project that has items awaiting your review.
2. If the items are contained in a Document, open it by browsing the Documents and Pages topic in
Navigation, or searching for the Document name.
If the items are created directly in the Work Item Tracker, click Work Items in Navigation to open
the Table view of project Work Items. You may want to expand Work Items to show the types that
exist in your project, and click a Work Item type to filter the table for that type. For example, if you will
be reviewing Requirements, expand Work Items and click on Requirements.
3. Open the Approvals panel, and select the My Approvals tab.
4. If there are any items awaiting your approval, the tab shows a number greater than zero in the
Waiting state. Click the drop-down control for Waiting, and on the menu choose Open Filtered
Document (if working in a Document), or Open Filtered Table (if working in the Tracker's Table
view).
After following these steps, a new browser tab opens that displays the Document or the Table filtered
to show only the Work Items awaiting your approval. These items list you as an Approving User in their
Approvals field. The items are in the Waiting approval state, meaning you have not yet marked them as
approved or disapproved. You can now proceed to review and mark items in this browser tab.
Tip
The default configuration of your My Polarion page lists items awaiting your approval.
In the Table view of Work Items, you can use the Query Builder to query for items with a specific approval
state, and/or with specific users designated as Approvers.
You can query for a specific approval state selecting the Approval State field as a visual query element,
and selecting the value(s) to query for. For example, to query for disapproved items, select Approval State
in the fields panel, and then select Disapproved in the values panel.
You can query for items having one or more specific users designated as an Approving User. Create a visual
query element and select Approvals in the fields panel, and then the name(s) of the approving user(s) in
the fields panel. You can query for items where you are designated as an Approver by selecting Me in the
fields panel.
For more information on using the Query Builder, see Search Work Items.
Procedure
1. Be sure you are working in the filtered Document or Table and have selected the My Approvals tab in
the Approvals panel.
2. If working in a Document, select the Work Item you want to approve or disapprove. If working in the
Tracker, select the item in the table.
3. In the Approvals panel, click Approve or Disapprove, depending on your decision.
4. Repeat the previous steps for other single Work Items in the Document or Table.
5. If working in a Document, save it to complete your review and log the approvals and disapprovals.
If working in the Table view, click Save Approvals in the Approvals panel to complete your review
and log the approvals and disapprovals.
Note
In some cases, marking items approved/disapproved one at a time is too time-consuming. For example,
suppose you review a specification document that has 50 Work Items in a Functional Requirements
section, and you decide all of them can be approved. You can mark all or any portion of the requirement
items in that section as approved in a single operation.
As with single Work Items, you should be looking at the items you need to review for approval in the
filtered Document or Table.
Procedure
1. Be sure you are working in the filtered Document or Table and have selected the My Approvals tab in
the Approvals panel.
2. If working in a Document, select all the Work Items you want to approve or disapprove. Note that the
selection must be contiguous; you cannot skip some item(s) in between.
If working in the Tracker, select all the items you want to approve or disapprove in the table using
the check boxes on each row, as you would for Bulk Edit. The selected items need not be contiguous
in the table. Alternatively, you can modify the query to display just the items you want to mark and
select them all using the check box on the table header.
3. In the Approvals panel, click Approve or Disapprove, depending on your decision about all the
selected items.
4. If working in a Document, save it to complete your review and log the approvals and disapprovals.
If working in the Table view, click Save Approvals in the Approvals panel to complete your review
and log the approvals and disapprovals.
Note
• As soon as you mark any item using Approve or Disapprove, a link named Revert approval state
change(s) appears beneath the buttons in the Approvals panel. You can click it to revert the approve/
disapprove actions on all the selected items.
• When you disapprove multiple selected items, a new Approval Comment is automatically created in
the Approvals panel, and you must enter a comment before you can save your changes. The Approval
Comment is applied to all the disapproved items.
• In a Document, if there is, for example, one item to be disapproved in between multiple items to
be approved, you need to do multiple select-and-approve actions, selecting and approving all items
before, and then all items after the disapproved item.
• Your user profile must contain a role assignment that is granted the permission to approve Work
Items. If you do not have this permission, you see a message when you try to approve or disapprove
items. Contact your project leader or portal administrator to resolve permissions issues.
The Approval Center feature tags Work Item comments to identify them as Approval Comments. The
following are useful points to know about Approval Comments:
• Approval Comments can be added to a Work Item at any time during the approval review process.
• Any user with the correct permissions can reply to an Approval Comment, and replies may have replies,
creating a comment thread.
• A user with the correct permissions can mark Approval Comments as Resolved. Resolved comments are
hidden, but can be shown to any user who wants to see them.
• An Approval Comment is automatically created when a single item or a group of items is marked as
disapproved. While not required, it is generally good practice to fill it in.
• Approval Comments are regular Work Item comments, stored in the Comments field of Work Items, but
are labeled as Approval Comments in the UI.
The Approvals panel displays a button for adding an Approval Comment when a Work Item or group of
Work Items is selected. If multiple Work Items are selected, the comment is added to all of the selected
items.
Procedure
1. Select one or more Work Items in a Document or the Work Items Table.
Tip
You can also click Add Approval Comment in the Document margin next to each Work Item, and on
the row of each Work Item in the Table view.
Procedure
1. In the Approvals panel, hover your pointer over the comment. Two icons and labels appear in the
comment.
2. Click Reply. A new reply comment appears in the panel.
3. Fill in the text of the reply.
4. Save the Document, or if working in the Table view, save the Approvals.
Tip
You can also reply to an existing Approval Comment using the Comments section of the Work Item
Editor in the Work Items Table view.
When the approval discussion is complete, it can be useful to mark the Approval Comments as Resolved.
This is especially true for items that were initially disapproved. These will always have one comment, and
often have some back and forth discussion until the item is revised to resolve the issues that resulted in
disapproval. Once the issues are addressed, marking the existing comments as Resolved hides them. The
item can then go through the review and approval process again without the distraction of the original
Approval Comments. Any user who needs to see the original discussion can unhide the resolved Approval
Comments.
Procedure
There are two ways you can show resolved Approval Comments, which are hidden by default when you
access the Work Item they belong to:
• In the Approvals panel header, click Pane Settings and check the Show Resolved Comments box.
Resolved comments appear shaded in the Approvals panel when shown.
• In the Table view of Work Items, scroll to the Comments section of the form and check Show Resolved
Comments.
It may be necessary to reopen some discussion thread around approval/disapproval of some Work Item.
To reopen a resolved Approval Comment, you must first show resolved comments (see View resolved
Comments). Once you are seeing resolved Approval Comments, there are two ways you can reopen one:
• In the Approvals panel, hover over the Approval Comment you want to reopen and click Reopen.
• Reply to an Approval Comment in the Approvals panel, or any reply in its comment thread.
Some Work Items are inevitably rejected (disapproved) during the initial phase of the approval process.
The items may undergo discussion in Approval Comments and other means, and eventually the items are
Procedure
5. Save the Document, or if working in the Table view, click Save Approvals.
Tip
You can reset the approval state of several Work Items at once. In Step 1 above, simply select multiple
Work Items.
If working in a Document, select contiguous items by dragging over them to highlight them. In the
Table or Tree view, check the box on the row of all the items you want to reset at once. (They need
not be contiguous in the listing.)
This section details how signatures work when approving a Work Item or changing its workflow status.
See the Sign documents and Approval sections for additional information on how signatures and the
approval process works and how to enable and configure them.
When a Work Item is approved, the name of the user that approved it, the date, and the approval verdict
appear in the comment section of the Work Item.
Tip
• Users with sufficient rights can Approve a Work item “On behalf of” the assigned approver.
(For example, if the assigned approver is on holidays but the item needs to be approved before they
get back.)
• Likewise the designated approver can “Disapprove” any approval made on their behalf.
• Polarion supports up to 20 approvals per Work Item.
In the example below, a system administrator is approving the Work Item on behalf of another Approving
User. When Approving User returns, they decide that the Work Item is not actually ready to be approved
and reverses the decision.
Procedure
Note
If you have sufficient rights, and want to add another Approving User, select the user in the
drop-down list on the left and click on the right.
Now let’s say that the Approving User returns from holidays and decides that the item approved on their
behalf is not actually ready to be approved.
Procedure
3. Click Save.
4. Enter your Username in the e-signature confirmation dialog and click Next.
Caution
Your browser might offer to or auto fill credentials in forms like e-signatures that use password
fields.
Edit your browser settings or enforce the related security policies on managed computers to disable
this.
6. The original approval comment will disappear and be replaced by the updated date, user, and
approval state information.
Obsolete approval states are removed from the Comments section of the Work Item, but the entire
approval process is still visible in the Work Item’s History.
You can require users to electronically sign a Work Item when changing the workflow status.
The latest workflow change will appear in the Workflow Signatures section of the Work Item.
Administrator's can configure the section so that if a workflow status is reversed, all signatures that
Reviewed and Approved a Reopened Work Item will be cleared from this section. (All signatures and
status changes are still tracked in the Work Item's History. See image above.)
Note
• If a Status change requires an electronic signature, you must change it in the Work Item Editor.
(You cannot change it inline via the Table and Tree Work Item tables.)
• The Workflow Signatures section is configured by default on fresh, 18.2+ Polarion installations,
but if you've updated from an older version, you need to add the following to the form layout
configuration:
<field id="workflowSignatures"/>
• See Require Signatures for Workflow Actions for details on how to make signatures mandatory
when changing a Work Items workflow status.
Procedure
3. Click Save.
4. If the Confirm Save dialog box appears, click Save.
Note
If you have previously selected Don't show this again in that dialog, it will not appear, and you can
go on to the next step.
5. Enter your Username in the signature confirmation dialog and click Next.
7. The Status will change and an entry will appear in the Workflow Signatures section of the Work
Item.
• The number of signatures that appear in the Workflow Signatures section also depends on your
workflow condition and function configuration.
The Priority field sets a priority value on a Work Item. This can be useful for project planning, progress
assessment, and reporting. Priority is a float type numeric value. It is possible to query for Work Items
based on the Priority value or range, and to show the results of such queries in report Pages.
There is also a set of priority "ranks". These are simply named ranges of priority values. The names of
the ranks and the range of numeric priority values is specified in the global and/or project configuration,
and are customizable by an administrator. For example, you might have ranks named High and Low with
numeric value ranges of 51-100 and 1-50, respectively. (For a listing of the default rank names and range
values, see the reference topic Priority Ranks.) The Priority field displays the current Work Item's priority
rank and numeric priority value.
The project workflow can be configured with an action that sets a default rank/value for new Work Items.
This is useful when new items are created via import from Microsoft Office documents. For example,
Priority of each new item might be set to Medium, and that rank might be configured to have a minimum
value of 50.0.
Tip
The Plans feature is recommended for project planning. See the topic Prioritize planned Work Items for
information on prioritizing Work Items in the context of a Plan.
Prioritization sidebar
This panel can be used to assign a Priority field value to multiple selected Work Items in the Table or
Tree views of the Work Items topic (Navigation Work Items). For conceptual and procedural
information, see Prioritize Work Items. This topic provides information about the components of the
panel. Please refer to the following figure:
Reposition buttons
These buttons move a selected Work Item or a selected group of Work Items upward or downward in the
table. On move, selected items are rescaled according to the new position in the table. The buttons, left to
right:
Rank selector
Displays a drop-down menu showing the priority ranks currently configured for the project. The priority
rank of all selected Work Items is set to the selected rank on save.
Priority field
Accepts a float value. The numeric priority value of all selected Work Items is set to the specified value on
save, overriding any value previously set in the Rank selector.
Enables you to prioritize the items in the table on a custom field rather than the standard Priority field.
The pick list displays all fields that are valid to use for prioritization in the current context. For more
information, see Prioritize on a Custom Field.
Rescales the numeric priority value of all Work Items currently selected in the table, limiting the maximum
value to that specified in the Top field, and/or the minimum value to that specified in the Bottom field (if
that field is present in the dialog box — it is only present when relevant).
If Keep Rank is selected, none of the selected items will have their value set above the maximum value
for their current rank. For example, if a selected item currently has rank Medium, and rescaling would set
the value higher than the maximum for that rank, thereby giving it a rank of High, that item will not be
rescaled to any value not occurring within the Medium range.
Rescales the numeric priority value of all Work Items in the prioritization table. Items will be rescaled
within the range specified in the Top and Bottom fields.
Keep Rank functions in the same way as in Rescale Selected, except that it operates on all items in the
prioritization table.
Tip
If you are prioritizing a set of Work Items that all have the same priority, as is usually the case when the
items were created by import from a Microsoft Office document, it is advisable to run Rescale All before
beginning to manually prioritize the items.
At some point, the project team and/or leader needs to prioritize their work, which means reviewing Work
Items and setting their Priority value. Priority can be set for a single item, or for many items at once. For a
single item, simply change the value of the Priority field and save the change.
Note
You can select one of the configured ranks, or set a numeric priority value. The latter is useful if you
want to give some item a higher priority while keeping the same general rank. For example, if an item
currently has priority set to High, that's configured with a minimum numeric value of "70", you might
assign the numeric value of "80". The item will still appear in results of queries for items with High
priority.
For setting Priority for multiple items at once (in a Scrum planning meeting, for example), Polarion
provides the Prioritization sidebar in the Table and Tree views of the Work Item Tracker.
When you invoke the sidebar, the table enters a special "Prioritization mode" in which the items in the
table can be dragged and dropped to prioritize them. You can drag a single selected item, or a group of
selected items (table rows in prioritization mode display drag "handles"). The table reflects priority with
highest priority at the top. By reordering the position of items in the table top-to-bottom, you reorder the
relative priority of all items in the table.
You can also use Inline Editing to quickly change the Priority field of several Work Items. However, Inline
Editing is an alternative of the Prioritization mode, meaning that the two cannot be used at the same time.
Tip
The set of items in the prioritization table is determined by the current query. Before invoking
Prioritization, build and run a query to retrieve just the items you will be prioritizing.
Before reordering the items in the prioritization table it is advisable to run the Rescale All operation
from the Settings menu of the Prioritization sidebar (see Prioritization sidebar). This enables
you to define the numeric range within which priority values will be assigned to the items in the table
based on their position in the displayed set of Work Items.
Procedure
1. Open the Table view in the Work Item Tracker (Navigation Work Items).
2. Open the Prioritization sidebar using the icon on the Table view toolbar (see the figure above).
Note
• You cannot open the Prioritization sidebar from a Document. You must use the Work Item Tracker.
If you want to prioritize all the items contained in some Document, you will need to build and run a
query that retrieves all the items in the Document.
• Inline editing is disabled if you open the Prioritization sidebar.
You can use one or more of several techniques to set priority value for items in the prioritization table:
• Assign a Rank
• Set a numeric value
• Reorder priority using buttons
• Reorder items visually
The Prioritization Panel can help you understand the interface for each of the above techniques.
Assign a Rank
You can assign one of the configured priority Ranks to items in the table using the Prioritization
sidebar.
Procedure
1. Select the items you want to rank by checking the box on the respective rows of the table in
prioritization mode.
2. In the Prioritization sidebar, click the Rank selector and choose the desired rank from the
drop-down menu.
3. Click Save to apply the rank to the selected items.
If all selected items had the same priority value before you assign rank, the Priority field of all selected
items will be set to the minimum value of the chosen rank. For example, if all items had a value of 50 and
you assign a rank whose minimum value is 70, all the selected items will be set to 70. If the selected items
had different priority values before you assign rank, they will all be set to the same value.
You can set the same numeric value in the Priority field of multiple Work Items in a single operation. On
save, the items will be repositioned in the table if the setting changes their priority relative to other items
in the table.
Procedure
1. Select the items you want to set by checking the box on the respective rows of the table in
prioritization mode.
2. In the Prioritization sidebar, enter the desired numeric value in the Priority field and click OK.
You can optionally select a different set of items and assign a number value to them in the same way.
3. Click the Save button to apply all settings to all changed Work Items.
The button set in the Prioritization table enables you to shift the position of one or more selected Work
Items up or down one row in the table, or to the top or bottom position. (Keep in mind that in prioritization
mode, top-to-bottom position in the table reflects highest-to-lowest priority.)
• Up - Acts as if you have dragged the selected items between the item preceding the topmost selected
item and the item preceding that one.
• Down - Acts as if you have dragged the selected items between the item succeeding the bottommost
selected item and the item following that one.
• Top and Bottom - Use the configured Priority Increment so that all the selected items are at the top or
bottom (depending on which button is pressed), and there are increment-sized gaps between them.
Warning
No operation (Up, Down, Top or Bottom) touches any other item unless the target point is between
items with the same priority. In that case, the priority values of items above the target point are rescaled.
Procedure
In prioritization mode, Work Items in the table are listed by priority from top (highest priority) to bottom
(lowest priority), except when all items have the same priority value. It is often the case with a set of newly
created Work Items or items imported from Microsoft Word or Excel that they have the same priority value.
It is important to understand that when you shift the position of some item(s), the relative priority of other
items above or below the new position may be changed, and this will be reflected visually in the table
(more items will become selected, and/or the rank colors of some items may change) and in the Range
Selector of the Prioritization panel (the label may change).
If you shift the position of a selected group of items, the items in the group will keep the same priority
relative to each other if they had different values to begin with. If they all had the same value, they will be
rescaled within the scope of all items in the set being prioritized.
Procedure
You can optionally rescale the relative priority of several selected Work Items to each other so that the
priority values are more evenly distributed. You can optionally limit the rescale operation to one of the
configured priority Ranks ("High", for example).
Procedure
2. In the Prioritization panel, click and choose Rescale Selected. The Rescale Selected dialog
appears.
3. Depending on the current priority of the items in the selection, the Top field or the Bottom field may
appear. Top lets you specify the maximum priority value for items in the selection. Bottom lets you
specify the minimum.
Review the field value, if present, and change if desired.
4. If you want all items in the selection to keep their current priority Rank, check the Keep Rank box.
This will prevent, for example, items having a rank "Medium" from being rescaled to fall into a rank
"High", or items having a rank "Low" from being rescaled into a rank "Lowest".
You can optionally rescale the priority of all items in the Work Items table (when it is in prioritization
mode). The set of items rescaled is determined by the current query. Be sure that your current query
retrieves all the items you want to rescale. For example, suppose you want to scale all the Work Items
contained in a requirements specification document. You would want to query for all Requirement type
items contained by the Document before invoking the Rescale All operation.
The Rescale All operation is designed to result in a reasonably even distribution of priority values among
all Work Items in a given set. You can specify the range of numeric priority values to be used. Scaling will
result in an even distribution of values within the specified range.
It is highly recommended to run Rescale All on sets of new Work Items before beginning to prioritize
them manually using any of the techniques previously described. For example, when a specification
document is imported from Microsoft Word, all the Work Items in the resulting PolarionDocument will
often have the same priority value. (Import rules that set different priorities based on content in the
original document could be defined for the import operation, but this is not always done by the person
importing a document.) Having an even distribution of values to begin with can facilitate the re-prioritizing
process.
Procedure
1. Be sure the current query has retrieved all the Work Items you want to rescale.
2. In the Prioritization sidebar, click and choose Rescale All. The Rescale All dialog appears.
3. Optionally change the default values in the Top and Bottom fields to specify the scaling range.
4. Click Rescale All to start the rescaling operation and close the dialog.
5. In the Prioritization sidebar, click Save to apply the changed priority values to all Work Items.
By default, the prioritization feature uses the standard Priority field of Work Items (field ID priority),
writing a value to that field. However, it is not necessary to prioritize items on that field. You can prioritize
items on any existing custom field, subject to the following limitations:
Procedure
4. In the Prioritization sidebar, click and select Change Prioritization Field on the menu.
5. In the Change Prioritization Field dialog, select the field on which to prioritize the items.
Note
The dialog lists only those fields valid for all the items and that the standard Priority field is always
present in the list.
Comments are an important tool for collaborating on Work Items. Comments can have multiple threads
that discuss different topics related to the Work Item. When stakeholders reach consensus, individual
comments and/or entire comment threads can be marked Resolved, which hides them from view unless
individual users opt to view them. In order to add comments and replies, or resolve comments, you must
be assigned a role that grants these permissions.
Caution
Work Item Comments should not be confused with Document Comments. They behave differently.
Procedure
2. In the Work Item editor, click on the top right to jump right to the Comments section.
4. Enter a Title for the comment thread, type your comments in the multi-line text field, and click
Save.
View Comments
The Comments section has several controls for adjusting the display of comments:
• Collapse All: Collapses the comments hiding the comment text so that only the header of each
comment is visible.
• Expand All: Expands any collapsed comments so that the text of all comments is visible.
• View list: Controls the way comments are indented. The Flat option indents all comments at the same
level. In this mode, comment threads are not readily apparent. The Tree option indents comments
according to comment threads, making it easier to follow any particular thread. You can individually
collapse the top level of any threads you don't want to read.
Every comment has its own Reply button that creates a new child comment. If a comment thread is
collapsed, you see only the Reply button for the top-level comment, which may or may not be what you
want to reply to. Expand any comment thread to see all comments and replies and to be able to access the
Reply control for any comment in the thread.
A frequent user need it to find comments written by a particular user. This is possible by querying for the
user ID of a comment author. The basic syntax of such a query is:
comments.author.id:USER_ID where USER_ID is the ID of the user whose comments you want to
find.
By itself, such a query will probably return many results, so you would most likely use it as an element in a
more detailed query. For example:
The above query looks for Defect type Work Items, updated "today" (i.e. within the 24-hour period defined
by the 2 date values), and having comments by user "jSmith".
When stakeholders reach consensus through comments and comment threads, it can be useful to mark
the comments and/or comment threads as Resolved. This hides them, after which individual users can
opt to view them. It is also possible to reopen resolved comments if a stakeholder decides that further
discussion is needed.
Note
Work Item Comments should not be confused with Document Comments. They behave differently.
Document Comments are stored with Document data and can only be viewed in the Document
Editor. Work Item Comments are stored in the Comments field of Work Items. Approval
Comments are Work Item Comments, stored in the Comments field, but which pertain to, and
constitute part of the audit trail for formal approvals.
See also Resolve Approval Comments, Resolve Document Comments and Threads.
Tip
Replying to any Comment in a resolved thread reopens the entire thread.
Procedure
1. In the Table or Tree views, select the Work Item containing the Comments you want to
resolve.
2. Select the Work Item with the comment(s).
3. Locate the comment thread you want to resolve in the Comments section of the selected Work
Item.
Procedure
1. In the Table or Tree views, select the Work Item containing the Comments you want to view.
Procedure
1. In the Table or Tree views, select the Work Item containing the Comments you want to
resolve.
4. Locate the comment you want to reopen and click Reopen this comment thread on the
comment header.
You can attach any type of file to a Work Item that will facilitate collaboration and/or implementation of
the Work Item. For example, for a defect, you might attach a screen capture image showing the problem
you encountered.
Procedure
2. In the Work Item Editor, click to jump to the Attachments section of the Work Item.
Your system or project administrator can optionally limit the file size of attachments. Contact your
administrator if you are unable to upload an attachment due to such restriction.
You can see the complete change history of the currently selected Work Item using History in the
Work Item Editor toolbar.
A Watch is a background process that monitors changes to a Work Item or Page and notifies any users
who have been specified as Watchers when a change occurs. The Author of a Work Item and the
Assignee are always notified of changes without the need to explicitly set a Watch. The Author and
Assignee of linked Work Items are also notified of changes.
Procedure
1. Navigate to the Work Item you want to watch and select it in the Table view.
2. In the Work Item editor toolbar, click and select Watch in the drop-down menu.
Procedure
1. Navigate to a Work Item you are currently watching and select it in the Work Items table.
2. In the Work Item editor toolbar, click and choose Stop Watching.
You can see a summary of all items to which you are assigned as a watcher. For server performance
reasons, this information is only provided on demand.
Procedure
1. Open your user profile (link on the My Polarion page or the tool view of Navigation).
2. In your user profile page, click the Watches button at the top.
A listing of items to which you are assigned as Watcher is displayed in the Table view of the Work
Items topic.
For any Work Item to which you have write access, you can add other users as Watchers of the item.
2. In the detail pane of the Work Item , scroll down to the Watches section.
3. Click the icon on the right.
4. Start typing in the name of the person you want to add as Watcher, then select them from the list.
You can add multiple Watchers at the same time, however, only people with a project-related role are
listed.
5. Click Save.
Note
When using Bulk Edit to set Watchers for multiple Work Items, only those users are listed that
have a project-related role for all projects of the selected Work Items.
You can print a listing of one or multiple selected Work Items to any printer to which your computer has
access. You can select a single Work Item for printing in the Table or Road Map views. You can also select
multiple Work Items for print in the Table view. Alternatively, you can formulate a query to retrieve exactly
the item(s) you want to print.
Procedure
1. Select the Work Item(s) you want to print in the appropriate Work Item view, or formulate a query to
retrieve just the item(s) you want to print.
2. Locate the button in the toolbar, and click it to drop down a menu.
Clipboard operations
You can quickly copy a Work Item's Link (URL) and/or ID and Title data to your computer's clipboard:
If you hover over a Work Item's Title in the Work Item Editor, the and icons appear.
◦ Copy ID
Copy the Work Item's ID to the clipboard.
◦ Copy ID + Title
Copy the Work Item's ID and Title to the clipboard.
◦ Copy ID + Title (as link)
Copy the link (URL) of the Work Item to your clipboard with the ID and Title as the link's label.
◦ Copy Link
Copy the Work Item's URL to your clipboard.
When hovering over the Smart Title of an item in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Work Item link with its ID and Title as the link's label.
Tip
The AllowClipboardHelper extension was recommended for clipboard support in some Polarion
versions. It it is no longer needed by Polarion and if you have installed it to Firefox, you can remove
it if you do not need it for other applications.
Administrators can configure restrictions on permission to read and/or modify Work Item fields. In
particular, the permission to MODIFY a Work Item field can impact users' ability to perform some
operations.
If a user is denied permission to MODIFY for Work Item fields, the ability to create new Work Items is limited
as follows:
Default value
Required field? configured? Result for user
YES YES Create is allowed. Default value is used, and user
cannot modify it.
YES NO Create is disallowed. Message is displayed to
user.
NO YES Create is allowed. Default value is used, and user
cannot modify it.
NO NO Create is allowed. No value is set. User cannot
modify field.
If a user is denied permission to MODIFY some Work Item field(s), and the user imports new Work Items
or reimports round-trip Work Items which hold values for the restricted fields, those fields are ignored by
the importer, the field values are not imported, and the user sees a message about the restriction.
This topic documents the standard Work Item data fields. The field names are typically shown in the Work
Item Editor, and in the column labels of the Work Item Tracker. They also appear in the helper panel of
the visual query builder.
Tip
See search using index fields for a complete list of available index fields.
When constructing text-based queries using the Lucene query language, you will need to reference Work
Item field IDs rather than field names. IDs are needed for some configurations, macro parameters, API calls,
etc. The table below lists all available fields and their ID values. Due to the way Polarion indexes Work
Item data, there are some Work Item fields whose field IDs must not be referenced in queries. Such fields
have one or more searchable Index IDs, which should be used in queries. These are noted in the Index IDs
column of the reference table. For example:
Note
The field IDs of the Time Point and Assignee fields are not referenced in the query portion of the macro.
Rather, the index IDs timePoint.time and assignee.id are used.
There are also some IDs that can be used in queries, but which are not fields of the Work Item itself.
Rather, they are fields in the Work Item Index. Consequently there is no Field ID, name, or description.
These are noted in the Index ID column of the reference table.
When a field is tokenized, it means that is it possible to search objects by sub-strings contained in the field.
This is most useful for querying for values in text fields such as Title and Description.
Sortable index fields can be used for ordering of the query results or searching by range. These index fields
contain special converted (lowercase) values of the fields, which are computed by special index functions.
(sortable)
attachments.author.name
(sortable)
attachments.content
(tokenized)
attachments.fileName
attachments.length
attachments.length.1 (one
word)
(sortable)
attachments.title
(tokenized)
attachments.updated
(sortable)
Backlinked Derived field backlinked backlinkedWorkItems via
Work Items containing links WorkItems
pointing from other linked
Work Items to the (All one word) WorkIte
referenced one (e.g. ms
WI-1). These links are
not stored in the WI-1 (All one
item, but are displayed word)
in the Linked Work
Items section of WI-1.
Categories This field enables categories categories.id yes
you to flexibly
categorize Work categories.name
Items according to
subsystem, customer, (sortable, lowercase)
or whatever criteria
you need. Category
values provide an
additional parameter
that can be used
in search queries.
You can assign one
or multiple Category
values to any Work
Item. For information
on configuring
Categories.
(hostname)
Hyperlinks Field that stores hyperlinks Not searchable yes
hyperlinks to other
resources inside the
Polarion portal, or
remote (internet URLs,
for example)
ID Identifier string that id id perman
uniquely identifies a ent
Work Item in the id.1 (tokenized)
Polarion repository.
id.2 (sortable)
No field label in the
Work Item detail. May
be displayed as ID in
table columns, dialogs
etc. elsewhere in the
user interface.
Time duration is
specified by an integer
value, or the literal
1/2 (or any other
fraction). Examples:
• 3d - 3 days
• 7h - 7 hours
• 1/2d - 1/2 day
Linked Field that stores links linkedRevisi linkedRevisions yes
Revisions to repository revisions ons
that are stored with
the Work Item.
Linked Field that stores links linkedRevisi linkedRevisionsDerived via
Revisions to repository revisions onsDerived
Derived that are derived from linked
recognized IDs in (All one word) Revision
commit messages. s
(All one
word)
Linked Work Field that stores linkedWorkIt linkedWorkItems yes
Items links to other Work ems
Items, either in the Uses special syntax.
same repository or
parentWorkItem:
ProjectId/WorkItemId
• 3d - 3 days
• 7h - 7 hours
• 1/2d - 1/2 day
Resolution Indicates the final resolution resolution yes
outcome of a Work
Item. The default resolution.1
values are defined
in the global and/or (sortable)
project configuration.
Keep in mind that
values in projects
may be from the
Project Template from
which the project
was derived. Also
keep in mind that
the visibility of the
field and/or the ability
to change the value
may be controlled
by the workflow
configuration and
bound to change of
the Status field.
In the default
configuration for this
field, the IDs of
Work Items with high
severity appear in
Red font in the user
interface.
Configure
Enumerations.
Status The Status field status status yes
indicates the Work
Item's process phase: status.1
"New", "Resolved",
"Closed", etc. Status (sortable)
values can be
configured in the
relevant enumeration
configuration.
Time duration is
specified by an integer
value, or the literal
1/2 (or any other
fraction). Examples:
• 3d - 3 days
• 7h - 7 hours
• 1/2d - 1/2 day
Title Each Work Item title title perman
receives a unique ent
ID automatically so (tokenized)
Title should contain
a short description title.1
of the Work Item.
The item can be
(sortable, lowercase)
described further in
the Description field.
Type The Type of a Work type type yes
Item is descriptive
of its nature. For type.1
example: "Bug", "Task",
"Change request". (sortable)
Depending on the
Type of Work Item,
some type-specific
fields can be present
updated.2
(sortable)
WatchedBy Lets you search for watchedBy yes
Work Items watched
by a specific user.
(watchedBy:userna
me)
Work Records Field that stores work workRecords workRecords yes
records. Work records
record blocks of time (stores dateonly-userId)
spent working on the
Work Item. workRecords.user.id
workRecords.date
(tokenized)
workRecords.comment
(tokenized)
Note
The legacy Live Plan feature (removed from Polarion in version 21 R1) used the following fields, listed in
the table above, for planning calculations. These fields remain present in Work Items, but are not used by
the Plans feature (now recommended for project planning). Project teams and managers can still opt to
set values for these fields, and use them in queries for reports or custom scripts.
• Planned End
• Planned Start
• workRecords
• Microsoft Excel
• Comma-separated Values (CSV)
• XML, with options for transforming to HTML, PDF, RTF, or plain text
• Microsoft Project
Note
Table custom fields have the following import/export limitations:
You can select a subset of all existing items for export using a Search query in the Table, or Road
Map views. (See Supported Microsoft Office versions.)
Procedure
1. In Table view, query the set of Work Items that you want to export.
(Some licenses allow you to export in additional views like Tree view, but all licenses support
Work Item export in Table view.)
2. (Optional) Select the boxes beside the Work Items that you'd like to export.
(Do not select any to export them all.)
Tip
If your exporting multiple Work Item types, select the Work Item Type that you'd like to use as the
default view first.
If you select multiple Work Item Types the following dialog confirms your default view.
Note
In Tree view, All found exports the full tree of Work items.
(Items that are duplicated in the tree are all exported and counted.)
If you select the same Work Item multiple times manually in Tree view and click Only selected,
then It is not duplicated and is only counted once.
(A single copy of each selected Work Item is exported without the tree structure.)
5. Select the Format that you'd like to export the Work Items to.
(Depending on the Format option you choose, Steps 6 to 8 may or may not be available.)
6. (Optional) Template: If shown, you can choose the template used to format the output.
(Your choice may be overridden by a custom plugin implemented by your organization.)
7. (Optional) Select fields from Available Columns that you want to include in the export and click Add
->.
(If you know the ID of a field that you want to add you can also enter it in Field ID and click Add.)
Select an added field and click Up and Down to change the column order.
8. (Optional) csv: Comma separated values : If this format is selected, you can Remember this
selection.
(The fields and columns you chose are remembered for future csv: Comma separated values
exports.)
9. (Optional) The Advanced options link leads to additional format-specific export options such as the
Charset.
Check the settings to be sure no changes are needed.
• Convert durations to decimal hours:
By default, time values are exported as fractions. (For example, ½ h).
Example
◦ The Priority value in Polarion is 1.11115.
◦ When you export to Excel it becomes 1.1112.
◦ Let's say you update it to 1.11127 in Excel.
◦ When you import it back to Polarion the four decimal place limit does not apply so it remains
1.11127
◦ But if you export it to Excel again it becomes 1.1113
11. Click to close the dialog or Show log to view the export's log.
Note
Export template override:
Organizations can optionally implement restrictions via the plugin API to influence the template used for
export to Microsoft Word and Excel, with restrictions on individual exports by individual users, to include
a watermark in the exported documents and/or to conform to other required policies.
If such a plugin is in use, the Export Work Items dialog shows a message under the Template field
when Word or Excel is selected as the target format: "The selected template may be substituted with one
that complies with company policy."
When you export Work Items to CSV or Excel Round-trip format, Work Items linked to and from the
exported items can optionally be included in the exported document. Items linked via derived links, items
cited in Subversion commit messages for example, can also be included in the export to CSV or Excel
Round-trip.
You include linked Work Items in the export by adding one or more of the following from the Available
Columns to the Selected Columns list in the Export Work Items dialog:
When you export Work Items to CSV or Excel Round-trip format, you can optionally include revision
numbers of any linked repository revisions in the output. Revisions linked to linked Work Items will also
be included. Revision numbers in the exported document are formatted as hyperlinks which lead to the
revision in your Polarionportal, displayed in the Repository Browser.
You include linked revisions in the export by adding Linked Revisions, from the Available Columns, to the
Selected Columns list in the Export Work Items dialog.
Note
If you are unable to use a template, you or your administrator can refine it. For more information see
Customize export templates for Microsoft Excel.
Before exporting items when viewing them using the Tree presentation option, you should specify the
sorting of the Work Items, including child levels. Remember that you can customize the fields that appear
in the table using the Customize Table option on the Refresh menu of the Work Items Table toolbar.
If the existing fields are not sufficient for the sort order you want, you can add one or more Custom Fields
and include them in the sort.
The tree presentation of Work Items in the Table view may be exported only to these formats:
There are two report options for exporting data from the Matrix view:
• MS Excel Table
• MS Excel Traceability Report
Excel Table
You can export data from the Matrix view as a table to Microsoft Excel (normal document, not Excel
Round-trip). Exported are rows and columns visible on the page, and only links with roles visible in the
page are exported.
When the Matrix view is current, the Export item appears on the Operations menu. Once
you have used the search controls to obtain the data you want to export, use this menu command to
launch the Export process. In the Export dialog, choose xls: Excel Table in the Format field. You have the
following additional options:
• Export link roles - Choose to display or not display the link role in the Excel cells. Yes makes sense only
if links of all roles are displayed. When links of all roles are exported, but role names are not exported,
then only one link from all links between two Work Items in the same direction is displayed.
• Export Work Item titles - Check to export Work Item titles. If unchecked only Work Item IDs are
exported.
• Export Revision messages (Revision matrix only) - Check if both revision names and messages are
exported. If unchecked, only revision names are exported.
• The exported document contains the export date, the queries used to obtain row and column Work
Items or Revisions, and in the cases when one particular link role is selected, the role of the link.
• Headers of rows and columns are hyperlinks to the Work Item or revision details in the Polarion portal.
• Links are indicated by an arrow like character (possibly with a role name next to it).
• Suspect links are marked by the ? character next to the link-indicator character.
• Direction of a link between a Work Item and a Revision is always from the Revision to the Work Item,
regardless of whether the link is created via a revision message or directly in a Work Item.
You can export traceability data from the Matrix view to Microsoft Excel. The export format is XML for
Microsoft Excel 2003. The traceability report has two columns: the first represents rows of the matrix, the
second contains list of all linked Work Items or Revisions that are present in a column of the matrix. Only
links with the role selected in the control are exported.
Export is possible even when the portal does not display the matrix due to a very large number of items
retrieved by the search query. A message in the portal informs you if this is the case, and the Link Role
combo box is filled with link roles defined for current project or for the global level.
When the Matrix view is current, the Export item appears on the Operations menu. Once you have used
the search controls to obtain the data you want to export, use this menu command to launch the Export
process. In the Export dialog, choose the xls: Excel traceability report in the Format field. The following
additional options are presented:
• Export link roles (Work Item matrix only): - If checked, the link role is displayed in the report cells.
Checking this option makes sense only if links of all roles are displayed. When links of all roles are
exported, but role names are not exported, then only one link from all links between two Work Items in
the same direction is displayed.
• Export Work Item titles - If checked, Work Item titles are exported. Otherwise, only Work Item IDs are
exported.
• Export Revision messages (Revision matrix only) - If checked, revision commit messages are
exported, otherwise only the revision names are exported. If the matrix does not retrieve revisions,
this option is ignored.)
• Include direct links (Work Item matrix only) - If checked, items linked by direct link are exported when
the search parameters retrieve only Work Items. The option has no effect if the matrix retrieves revisions.
• Include backlinks (Work Item matrix only) - If checked, backlinked items will also be exported when
the search parameters retrieve only Work Items. The option has no effect if the matrix retrieves revisions.
You can export Work Items from your projects to an XML structure used as input for transformation to
various file formats by means of XSL templates stored in the Polarion system. The procedure is the same as
export to other formats:
• Invoke the Export Work Items dialog box from the menu in any Work Item where Export is present
on that menu.
In the Export Work Items dialog's Format field, select any option that begins with or contains xml or XML.
If multiple templates are present, select the desired template in the Templatefield and click OK. Either save
the exported XML document to your local file system, or opt to open it in whatever application is registered
for the file format created by the selected template.
The Export Work Items dialog provides the following XML export options in the Format field. Some both
export the selected Work Items to XML, and also invoke XSL transformation processing to transform the
output to different file formats. The options are as follows:
• html: XML Export: Content is exported to XML and transformed via XSL processor to HTML.
• pdf: XML-FO Export: Content is exported to XML and transformed via XSL and FO processors to PDF.
• rtf: XML-FO Export: Content is exported to XML and transformed via XSL and FO processor to RTF.
• txt: XML Export: Content is exported to XML and transformed via XSL processor to plain ASCII text.
• xml: XML Export: export to XML transformed via XSL processor to a different (or the same) XML
structure.
The above options are present when the Work Items table is in the Flat (table) presentation mode. If the
Work Items table is in Tree (hierarchical) presentation mode, a subset of these options is presented with
only those options that are supported for the Tree mode.
Note
Custom XSL Templates: You can develop custom XSL templates that transform exported Work Items
according to your own requirements. For information, see: Customize XML Export, and XML Export
Schema.
PDF and Non-English Characters: In order for PDF to be exported properly when Work Items contain
non-English characters, the *-fo.xsl template that is used for the export (.polarion/tracker/
export_templates) must explicitly name the font-family for all text in the resulting FO file. This
is most easily done by setting the font-family attribute of the fo:root element. For example: font-
family="Arial" (used in the default Sample-fo.xsl).
If this font-family specification is not provided, FOP replaces non-English characters with # in the
resulting PDF output.
The export option xlsx: Microsoft Excel exports Work Items in a round-trip format for Microsoft Excel,
enabling an external user to edit Work Item content in Excel. A Polarion user can then import the edited
Excel sheet back to Polarion, updating the Work Item content from the externally edited Excel document
and/or creating new Work Items defined externally in the exported Excel document. If Work Items are
exported from a Document, it is possible to allow changing of the Document structure externally in the
exported Excel worksheet.
Polarion also supports export of Work Items to Microsoft Project enabling sharing of the current Polarion
project plan with users of Microsoft Project.
The menu in the toolbar of the Work Item Editor provides access to several useful actions you can
perform on Work Items.
Tip
If you have a Work Item with custom fields and you want to make sure that all its fields are
duplicated. Use this option.
2. Duplicate a Work Item within a document lets you quickly copy a saved Work Item and selected
data within the same document or to an entirely different document - even one that resides
in another project. (Provided you have the CREATE NEW Work Item and MODIFY CONTENT
permissions for the target document and project.) You can create either a new Work Item based
on the clipboard data or a Referenced Work Item.
Fields that are duplicated:
• When duplicating a Work Item within the same document.
- Only the editable fields that are visible in the document.
(If you have custom fields that are exposed in the Work Item layout, they will not be duplicated
when copy and pasting.)
- Applies to both saved and unsaved Work Items.
• When duplicating a Work Item from one document to another.
You can choose one of the following options from the Duplicate drop-down list.
- Basic will copy the Title, Description and Test Steps values.
- Advanced will copy the Basic option fields plus the Priority, Severity, Links, Attachments and
Custom Fields.
3. Copy and Paste an unsaved Work Item within the same document.
(This will only copy its highlighted content. No additional data will be copied.)
• Document Comments added to the Work Item's Description will be removed when you duplicate the
Work Item.
(Document Comments should not be confused with Work Item Comments. They behave differently.)
• When duplicating a single Work Item, there is an option to Preview. A preview appears in the editor and
is not created until Create is clicked.
(There is no Preview when multiple Work Items are selected.)
• By default, duplicated items have a link to the original item with a "Relates to" link role.
Existing links between source Work Item(s) are duplicated as links between the same duplicated items,
including structure links if items belong to a Document.
• Votes and Watches on the source Work Items are NOT duplicated in the target Work Items. (But they do
appear in the preview.)
• If you duplicate items into a different project, be sure you have CREATE NEW Work Item and MODIFY
CONTENT permissions for the target project.
When duplicating a single Work Item, you can select the role of the link that will lead from the duplicate to
the original. You can select only the link role from those allowed by the Work Items configuration between
the type of the duplicate Work Item and that of the original. The Role list in the Duplicate Work Item
dialog box provides one additional option in addition to the roles: -- not selected --. Choosing this item in
the list results in no link between the duplicate and the original items.
Tip
When the Duplicate Work Items dialog box opens, the preselected link role in the Link Role list is the
one that is set as default in the Work Item Link Role enumeration in the project configuration, if any is
specified.
For example, suppose you are duplicating a Work Item of type Requirement, and you choose User Story
as the type of the duplicate. The resulting item will be of the User Story type. The available link roles in
the Roles list will then be the ones that the link roles configuration allows to exist between a User Story
and a Requirement - relates to, depends on, implements, or -- not selected --, for example. Assuming
the default link role for this project is depends on, it will be the preselected role in the list.
The maximum number of Work Items that may be duplicated at once is 100. You can select more, but you
will need to process them in chunks of 100 or less.
(See Bulk Editing a Large Number of Work Items for more information.)
If more than the maximum is selected, the Duplicate action appears in the Viewer/Editor section
rather than the button.
Duplicate a Work Item from the Work Item list in Table View
You can duplicate existing Work Item(s) in the same or a different project. You can duplicate them as a
regular Work Item, or associate them with a Document .
Procedure
1. Select the item to duplicate in the Work Item Table view list.
2. In the Work Item Editor toolbar, click then Duplicate in the drop-down menu.
(The Duplicate Work Item dialog appears.)
3. In the Project list, select the target project for the duplicate Work Item. The current project is
selected by default.
In the Type list, choose the type for the duplicate Work Item. It need not be the same type as the
item you are duplicating.
4. If you want to create the duplicate Work Item as a regular item in the target project, select Create
in Project. If you want to create the duplicate Work Item in a Document in the target project, then
select Create in Document option, and then select the Space and Document names in the Space
and Document lists, respectively.
5. (Optional) Click Preview to preview the Work Item in the bottom section of the screen before clicking
Create.
6. Click Create to create the Work Item(s) without a preview.
If the source Work Item is one that has been approved using an electronic signature, any new Work
Items derived from it through reuse will not show any indication of the source item's signature, and the
new items are not approved or electronically signed. The new item(s) must also be reviewed, approved,
and e-signed.
You can quickly change a Work Item type to another type. For example, if the Work Item is currently a
Task, you might change it to a Defect or Change Request.
Procedure
1. In Table (or other views) select the item you want to change to a different Work Item type.
3. On the drop-down menu, choose Change Type to, and in the sub-menu, select a Work Item type.
Note
You cannot change the Work Item type if the Type field is read-only in the project configuration.
If a Test Steps table layout in a Work Item form does not match the layout in Administration (for
example it does not match the configuration for the specific Work Item type, or the layout does not match
the All types default configuration if the specific Work Item type configuration does not exist), then a
yellow ribbon appears in the Test Steps section when editing the Work Item form.
This yellow ribbon lets you know that the table layout is not up-to-date. It lists the names of the columns of
the new layout, and there is also a link where you can update the layout.
Procedure
2. Click Update.
Caution
If the new layout has fewer columns than the old one, data from deleted columns is not
automatically transferred, so you must do it manually to avoid losing any data.
Note
Changes in the Name, Column Width, and Description of a Test Step table columns configuration
appear in the Test Steps tables automatically, you do not need to trigger the update manually.
When focused on any Work Item in the Work Item Editor, you can quickly create a new Work Item and a
link in a single operation. You can create two basic link types this way, each having several possible link
relationships:
• Linking Work Item: Create a new Work Item and an incoming link to the current item from the new
item.
In the default project configurations in project templates, a new Linking Work Item can have any one of
the following relationships to the current Work Item:
Procedure
Procedure
1. In the Work Item browser, select the Work Item that you want to create a new Linking Work Item
for.
2. Create a Linking Work Item by doing one of the following:
(If you click above the Work Item you create a Linked Work Item).
Choose the type and the link relationship for the new Work Item you want to create.
In the default project configurations in project templates, a new Linked Work Item can have any one of
these relationships to the current Work Item:
Procedure
1. In the Work Item browser, select the Work Item that you want to create a new Linking Work Item for.
2. Create a Linked Work Item by doing one of the following:
(If you click below the Work Item you create a Linking Work Item).
Choose the type and the link relationship for the new Work Item you want to create.
Tip
Linking Work Items is vital for creating traceability. See the Link types and terms, section for details.
Common linking scenarios include:
When you select multiple Work Items in the Work Items table, Copy IDs appears on the menu
below the table. It lets you copy the IDs of all the currently selected Work Items to your clipboard in the
following format:
This can be useful if you need to construct a text-based Lucene query for use in a script or script-based
Widget. You can test it by clearing the current query in the Work Items table and pasting the copied string
directly into the Query Builder field.
Caution
The copied string works only in text-based queries. If you paste the copied string into the "ID" element
in the Query Builder it will not work. If the current query contains visual query elements, you can,
however, append the string from your clipboard directly into the Query Builder field after the visual
elements.
• It is a Test Case Work Item that still remains within an existing Test Run.
• The Work Item is currently linked to any other Work Item(s).
• The Work Item was linked in the past (you can determine this from its History). The history of
the formerly linked item(s) will contain links to the Work Item you propose to delete. If you delete it,
traceability which might be needed at some future time will be broken.
Rather than deleting such Work Items, it is recommended to set its severity to the lowest value, and add
an appropriate comment.
If the Work Item has never been linked to any other (you can verify this in its History), then you can delete
it. Deleting a Work Item triggers a workitem-deleted system event which results in notifications being
sent to the notification targets configured for that event in Administration. All deletions and removals of
Work Items appear in the Activity stream.
Note
If the Work Item you want to delete is defined in a Document, it is recommended to delete the item via
the Document Editor rather than the Table or other view of Work Items. See Work Item Recycle
Bin.
Your user role must have the DELETE permission, and access rights for the repository folder that contains
the Work Item. By default, the project_admin role has this permission. (The System Administrator also
has these permissions.)
Note
If a Work Item is part of a Derived Document, Delete is disabled in the Work Item Editor.
(Even users with DELETE permissions will not be able to delete them.)
• If you select more than 20 items for Bulk Editing and want to Delete selected items, then Work Items
that belong to Derived Documents are skipped.
Procedure
1. After logging in with necessary permissions, open the project containing the Work Item(s) to be
deleted.
2. Locate the item you want to delete in the Table view of the Work Items topic and select it. You
may select multiple items (as for Bulk Editing) to delete all the selected items at once.
3. In the Work Item Editor toolbar (lower part of the page), click on and choose Delete.
Note
If more than 20 items are selected for Bulk Editing, the Delete action appears along with several
others in the Work Item detail pane and the menu button is disabled.
In order to understand how to move Work Items, some understanding of the underlying storage types is
necessary. You can move Work Items from one type of storage to another.
• XML Storage:
Work Items created in the integrated tracker exist in XML storage. Think of this as "standard" or "normal"
storage for Work Items.
• Document: Work Items rendered in the user interface exist in XML at the lowest level and are stored in
a container which maintains their structure. For example, rendered in a Document-like way and in the
various views of the Document's Work Items (such as Table) in a tracker-like way.
Tip
While there is no limit to the number of Work Items you can have in a LiveDoc, we recommend
keeping it under 5000.
• Module (legacy): Work Items in Polarion version 2010 and some earlier versions exist in modules--
special containers that maintain structure and sorting. They are deprecated as of version 2011, but
may still exist in projects created with earlier versions. In terms of storage, Modules are the basis for
Documents. The underlying storage is quite similar, the user interface is quite different.
Moving of Work Items from one type of storage to another is probably not something you would do
frequently, but you may occasionally encounter a need for it. Users of pre-2011 Modules in particular need
to use Work Item moving to migrate from Module to Documents. Another scenario could be Work Items
such as requirements or test cases that were originally defined in an office document and created in a
Polarion Live Document during import from Word. You might prefer to manage such items in standard
tracker storage, so you would move them out of the Document.
Keep in mind the following information when planning to move Work Items:
You can move Work Items stored in legacy pre-2011 Module to a Document. You need to create the
target Document before initiating the move. This migration requires an intermediate move to XML
storage, then from XML storage to the target Document. Please contact Polarion Technical Support if
migrating legacy document content is an issue for you.
You can move Work Items stored in one Document to another Document. For example, both
requirements and test cases might have been defined in the same office document that was imported
into Polarion, so both Work Item types exist in one Document, and you want to move the test cases to a
separate Document.
• A Document structure role can only be used for Derived document structure links.
(It's not possible to create links with this link role for a Work Item that's contained within a Document.)
• When moving a Work Item from one Document to another, all existing links that use the Reserved
Document structure link role are removed.
• Document Comments added to the Work Item's Description will be removed when you move the
Work Item.
Note
Document Comments should not be confused with Work Item Comments. They behave
differently.
Procedure
1. Create a Document to receive the moved Work Items if a target Document does not already exist. It
can be in the same Spaces as the source Document, or another Space.
2. Open the Document containing the Work Items you want to move, and open the Table view to
see the items in tracker format.
3. Select the items you want to move (check the box to the left of each item, as you would for Bulk
Edit). You can run a query to reduce the number of items in the table to make it easier to browse to
and select the ones you want to move.
4. In the Work Item Editor toolbar, click , and choose Move. The Move Work Item(s) dialog
appears.
5. In the dialog, select the Into Document option. The Space and Document lists become enabled.
6. If the target Document resides in a Space other than the one shown in the Space list, select the
correct Space in the list.
7. Select the target Document in the Document list, and click OK.
Note
Document Comments added to the Work Item's Description will be removed when you move the
Work Item. (Document Comments should not be confused with Work Item Comments. They behave
differently.)
Note
If a Work Item is part of a Derived Document, Move is disabled in the Work Item editor. If you
select more than 20 items for Bulk Editing and want to Move selected items, then Work Items that
belong to Derived Documents are skipped.
1. Open the Document containing the Work Items you want to move, and open the Table view to
see the items in tracker format.
2. Select the items you want to move (check the box to the left of each item, as you would for Bulk
Edit). You can run a query to reduce the number of items in the table and make it easier to browse to
and select the ones you want to move.
3. In the Work Item Editor toolbar, click , and choose Move. The Move Work Item(s) dialog
appears.
4. In the dialog, select the Out of Document option and click OK.
You can move Work Items from standard XML storage in the track to a Document. For example, you
might discover that someone created new Work Items directly in the tracker which should really be part of
a Document.
Note
Document Comments added to the Work Item's Description will be removed when you move the
Work Item. (Document Comments should not be confused with Work Item Comments. They behave
differently.)
Note
If a Work Item is part of a Derived Document, Move is disabled in the Work Item editor. If you
select more than 20 items for Bulk Editing and want to Move selected items, then Work Items that
belong to Derived Documents are skipped.
Procedure
1. If the target Document to receive the moved Work Items does not already exist, create a new
Document.
2. In Navigation, select the Work Items topic. Optionally use one of the sub-topics to filter for a
single Work Item type.
3. In the Table view, select the items you want to move (check the box to the left of each item, as
you would for Bulk Edit). You can run a query to reduce the number of items in the table to make it
easier to browse to and select the ones you want to move.
4. On the Work Item Editor toolbar, click , and choose Move. The Move Work Item(s) dialog
appears.
5. In the dialog, select the Into Document option. The Space and Document lists become enabled.
6. If the target Document resides in a Space other than the one shown in the Space list, select the
correct Space in the list.
7. Select the target Document in the Document, list and click OK.
When you export any set of Work Items using the xlsx: Microsoft Excel option, the output is written to
a special round-trip format for Microsoft Excel. An external user may optionally edit Work Item content
in Excel and/or create new Work Items for import into Polarion. A Polarion user with the necessary
permissions can then import the edited Excel workbook back to Polarion, updating the Work Item content
from the externally edited Excel worksheet, and/or creating new Work Items defined externally in the
exported Excel workbook.
If the Work Items were exported from a Document with the necessary export options, it is also
possible for an external user to change the Document's structure externally in Excel. The structural
changes are reflected in the online Document when the Excel worksheet changes are re-imported to
Polarion.
Excel export may be run from any scope: Repository, Project group, or Project. Re-importing
of an Excel workbook which contains modified Work Items can also be done in any scope. However,
re-importing of Excel workbooks which contain new Work Items is only allowed in the project scope.
Exported Work Item fields which are writable in the portal may be optionally locked in the Export Work
Items dialog during the export procedure so that users of the exported Excel file cannot easily change
the field value. If an advanced Excel user does manage to change the value of a locked field in Excel, the
change is ignored when the Excel file is imported back into Polarion. (Note that fields which are read-only
in the portal display the locked lock icon in the dialog, and are not unlocked when clicked.)
Warning
• Cross-references contained in Polarion Work Items are lost when those Work Items are exported
to Microsoft Excel for round-trip. This is due to limitations in Excel, and there is no work-around.
If a round-trip workbook to which cross-references were exported is subsequently re-imported, the
original cross-references in Polarion will no longer work, and must be manually restored. Always check
for cross-references in Work Items you plan to export to Excel for round-trip. Either avoid exporting
items containing cross references, or plan to repair them after round-trip operations are completed.
• Any advanced text formatting and lists (bullet, etc.) implemented in the exported Excel document are
lost upon re-import to Polarion.
• Images are not currently supported in the Description field, or other rich-text fields, of Work Items
modified or created in an exported Excel round-trip worksheet. If images are included, they will be
lost when the workbook is re-imported into Polarion. A warning is displayed and the user performing
re-import may opt to cancel the operation.
Mathematical formulas contained in rich test fields of Work Items are subject to the same limitations
as images, because they are rendered as images when not in edit mode.
• If you select Export Priority as a number when exporting to Excel and Priority is one of your chosen
columns, Polarion rounds the float value to four decimal places. If you add additional decimal places
in Excel, they remain when reimported to Polarion but get rounded off again when exported back to
Excel.
Example:
◦ The Priority value in Polarion is 1.11115.
◦ When you export to Excel it becomes 1.1112.
◦ Let's say you update it to 1.11127 in Excel.
◦ When you import it back to Polarion the four decimal place limit does not apply so it remains
1.11127
◦ But if you export it to Excel again it becomes 1.1113
Formatting of the Excel Round-trip output is controlled by an export template. Polarion provides, and by
default uses, an Excel template named Basic.xlsx. Additional templates are provided in the original
Polarion installation and are available in the Template field of the Export Work Items dialog when
exporting for Excel Round-trip. An administrator can download any export template and modify it locally
to create a customized version of the original template, and/or additional templates. When uploaded to
the portal, the template names appear in the Template field where users exporting Work Items can select
which one they wish to use for the round-trip export to Excel.
Note
The size of each template's sheet is limited. For more information please see Customize export
templates for Microsoft Excel.
An export template may also specify which columns should be locked in the exported Excel file when
an export operation uses the export template. This both saves time for end users, and provides control
to prevent external or otherwise unauthorized users from inappropriately changing exported data, while
permitting them to view it. Even if a user of an exported template-based Excel file manages to change data
in a locked column, the change is ignored on re-import to Polarion.
Excel export for offline Test Case execution supports export of Test Cases with multiple Iterations of Test
Steps. By default, the export template is configured to append a label for each Iteration to the Title column
in the exported workbook. It is possible to configure which field displays the Iteration number in the
property Append Iteration Label to Field in the hidden Polarion sheet. The default is the Title field.
For more information, see: Customize Export Templates, Customize export templates for Microsoft
Excel and Configure Test Export Templates.
The default templates can contain the same expandable variables as used in PDF or Word export, as well as
one for a query (in cells and header/footer). For information on these variables, see Configure PDF Export.
Native Excel comments present in cells are imported to Polarion as new Work Item comments. The
Polarion tab of the Excel Round-trip export template contains the property New Comments Column
which contains a format for the Comments column header. The default title for imported comments is the
value of the header of the comments column.
If Work Items containing Document comments are exported for Excel Round-trip, and the Work Item
Description field is allowed by the exporting user to be editable in the exported Excel workbook,
a placeholder {comment:id} is inserted into description text in the exported Excel workbook. This
preserves the comment marker for the round-trip process and should not be removed from the exported
Excel document.
The user of an exported Excel workbook can define a new Work Item by adding a new row in the table of
exported Work Items on Worksheet one. The user should leave the ID column blank. The Excel Round-trip
importer creates IDs for newly defined Work Items during the round-trip import process.
To insert a row into the Work Items table in the Excel round-trip document, select a cell in the table, right
click on the row number and select Insert. A new row is inserted before the current row. Note that in
a newly exported Excel document, one empty row is present. This row is locked and is present only so
the user can insert new rows above it for new Work Items. It remains as the last row in the table, and its
presence does not affect anything in the re-import to Polarion process. If you encounter a table with no
empty first row present (perhaps exported from a Polarion version where the exporter did not create an
empty row), you can add a first row, but it will not be editable, as just described. Simply add another row
above it and proceed to define a new Work Item.
Creation of new Work Items via Excel Round-trip import is only allowed in the project scope (i.e. not in
project group or repository scopes). Be sure you have the correct project open when you import Excel
workbook in which new Work Items are defined.
Note
• You can only import the Work Item Type defined by the Excel Export Template or the default Work
Item Type of the project you're working in.
You will not be able to select types from the Excel drop-down menu.
• Make sure that fields like Description or Title that correspond to columns in Excel are unlocked before
adding Work Items.
• If you insert new Work Items between the Test Steps of another Work Item, the import will fail and
log an exception.
Workflow configuration for projects often includes some initial workflow action which is executed for
newly created Work Items. For example, a value may be set for the Status field. If no initial action is
specified for the Work Item type in the project workflow, then the user-specified values for all editable
fields will be set in Polarion when the Excel workbook is re-imported into Polarion. However, if an initial
workflow action is configured, then any field values set by the initial workflow action will override user-
specified values set in the Excel sheet. For example, suppose the Excel user creates a new Work Item
in Excel, and sets the Status field to Accepted. If the project's workflow configuration has an initial
action which sets the value of the Status to Draft for new Work Items of the new item's type, then the
workflow action's setting overrides the Excel user's setting, and the Status field will be set to Draft after
the re-import operation.
For a general overview of exporting Work Items, please review: Excel Round-trip overview.
Procedure
Categories
Comments
Created
Document
Externally Linked Work Items
Has Suspect Links
Hyperlinks
ID
Linked Data Resources
Linked Revisions
Linked Work Items
Outline Number
Planning Constraints
Planned End
Planned In
Planned Start
Project
Repository, Project
Status
Type
Updated
Work Records
Note
Custom Enum fields can be edited during the round-trip process, but only if they do not Multi valued
flag in their definition.
Tip
• If the Work Items being exported to Excel are contained in a Document, the Export Work Items
dialog provides the advanced option Allow Document structure changes in Excel. If checked, then
an external user will be able to modify the structure of the online Document in Excel.
After export, all columns will be editable in the exported Excel workbook regardless of their locked/
unlocked status in the export dialog. All externally made structural changes will be reflected in the
source Document when the exported and modified Excel workbook is re-imported to Polarion. The
only exception is Work Item fields that are always marked as locked (i.e. read-only) by Polarion in
the export dialog... Linked Work Items, for example. Such fields, when exported with the option to
allow structural changes, will not be locked in the exported workbook, and can be changed by the
user. However, any change to these fields will be ignored by the importer when the workbook is
re-imported to Polarion.
Structure in the exported workbook is shown by indentation. The first column is left-aligned to that
indentation is visible.
• You can optionally view the export template before finishing the export by clicking on the Show
template link. You are then prompted to download and save the template file, or download and open
it in Microsoft Excel.
• Columns used in the template for some calculation cannot be removed from the Selected Columns
list because they must be present in the exported file in order for the calculation(s) defined in the
template to work. Such columns appear in Italic font.
• In addition to the Add and Remove buttons, columns can be added to or removed from the list boxes
by double-clicking a column name in either list.
You can edit PolarionTest Steps or add new steps in Excel with Excel Round-trip.
Note
• The export limitations that apply to other Polarion fields also apply to Test Steps. (Advanced
formatting and images are lost.)
• You can also add a new Work Item in Excel. (The limitations described in the Define new Work Item
section also apply.)
You can also enter new Test Steps for this newly defined Work Item. (If it is allowed by the type
specified in the hidden Polarion sheet.)
Add or Edit Test Steps in Excel and Import them back to Polarion:
Procedure
1. Add the Test Steps column when exporting your target Test Case(s) from Polarion.
2. Edit Test Steps in Excel.
3. Import Test Steps edited in Excel back to Polarion.
Procedure
1. Before you can edit Test Steps in Excel, you must add Test Steps as a Selected Column when you
export the Test Cases from Polarion.
2. Select the Test Case(s) to export in Polarion.
3. Click Export.
4. Select xlsx: Microsoft Excel as the Format.
5. Select a Template. (If you are not sure what template to use, just leave Basic selected.)
6. Select Test Steps from Available Columns and click Add.
Tip
• By default, the Test Steps column is visible and unlocked. (Anyone can add/edit the Test Step
information in Excel.)
• (Optional) Click on Test Steps in the Selected Column list to lock it in Excel.
(The Test Step column is visible in Excel, but is read-only.)
• (Optional) Click on other locked columns in the Selected Column section to unlock them
for editing in Excel.
7. Click OK.
The following warning appears.
9. Click or Cancel to close the Export Work Items dialog box or Show log to view the export's log.
Procedure
Tip
To delete a Test Step, delete all contents of the target Test Step.
(You cannot delete the entire line because there are always protected cells in the exported table.)
Procedure
4. Click Start.
(Optional) Select Overwrite Conflicts to overwrite conflicting information with the most recent
version.
(See Re-import an exported Excel Document for more information.)
The changes are imported back into Polarion and are listed in the Import Work Items dialog box.
5. (Optional) Click view... to launch a new browser tab listing the changed Work Items in Table
view.
6. (Optional) Select the Work Item you added Test Steps to and click Edit.
The steps you added appear in the Test Step section of the Work Item.
Limitations
Avoid using the same Names with different IDs (or the other way around) in a single Project. You may lose
data from those columns during Excel Round-trip. You can reuse columns with the same Name and ID.
We identified the following issues regarding Test Steps used in Excel Round-trip:
• For columns with the same Names but different IDs, only one column per Name is exported to Excel.
• For columns with the same IDs but different Names, the columns might not be sorted properly in the
exported Excel file.
• For columns with the same Name in Excel, only the last column is imported to Polarion.
• All of these issues apply for IDs and Names of any Custom Field as well.
An exported Excel workbook that has been modified can subsequently be re-imported to Polarion. All the
Work Items modified in the document are updated with the changes from the document, a new entry
is logged in history, and a workitem_updated notification event is triggered for changed Work Items
causing the notifications to be sent as defined in the notifications configuration.
If new Work Items were defined in the Excel workbook, they are created in Polarion by the importer. The
following points are useful to note:
• If Auto-assignment is configured for the project, the new items are automatically assigned and
notifications are sent to the assignee(s).
An Excel workbook can only be imported into the Polarion project where it was originally exported from. If
imported to a different project, the import fails with a message and a link to the log file that contains the
details. It is possible to export Work Items from the project group scope, but these exports are only "one
way"... Excel workbooks exported from a project group and then modified cannot be re-imported.
Caution
• Exported Work Items appear in a table in Excel. If you want to add a new Work Item, add a row to the
same table.
(Work Items added below the table will not be recognized when imported back into Polarion.)
• Do not assign a Polarion ID when creating a Work Item in Excel. (Polarion will assign an ID during the
import.)
Procedure
1. Open the project that the Excel workbook was exported from, and open the Table view of the
Work Items topic in Navigation.
2. Click Import on the top left to launch the Import Work Items dialog.
3. In the Format field, select xlsx: Microsoft Excel Round-trip Changes.
4. In the File field, click Choose File and select the file you want to re-import.
5. (Optional) Select Overwrite Conflicts. (Overwrites conflicting information with the most recent
version.)
Potential re-import conflicts and how Polarion treats them:
6. Click Start to upload the file and start the import process.
• If the import succeeds, an Import successfully finished message appears.
• If the import fails, an Import failed message appears. (Click Show log to learn why it failed.)
• If you selected Overwrite Conflicts, details on what was created and changed also appear in the
confirmation dialog.
7. Polarion lists all the Work Items that are discovered during import in Table view.
Note
New Work Items created in Excel appear in the Document's Recycle bin.
(Until you select where you want the in the Document.)
9. Click where you want to add the Work Item(s) in the Document.
10. Select the Work Item(s) that you'd like to add and click or Insert at the top of the sidebar.
The Work Item(s) are added to the Document.
11. When you've completed adding all of the Work Items, click on the top left.
Polarion can be configured to support multiple human language translations of Work Items. For example,
an international company could write requirements in English, and provide translations for Japanese-
speaking suppliers in Japan and French-speaking key customers in France, Canada, or Africa.
When correctly configured, a Title and Description field for one or more additional languages appear
in the Custom Fields section of the Work Item Editor in tracker views, and when Work Items are
contained in Documents, users can switch the language. After an administrator configures your system
for multi-language support, your translators can supply a translation of Work Item Titles and Descriptions
previously written in the default language. After translation, users who access Work Items can see the
content in their preferred language.
The basic process for adding support for multiple languages in Work Items follows (some steps require
Administrator permissions):
Information on configuring multi-language translation for Work Items can be found at: Configure Multi-
language Support.
The assumption is that Work Items will first be written in some default language, and translation(s) will be
done afterwards. Translation is always performed in the Tracker view. If a Work Item exists in a Document,
the translator must switch to that view.
Procedure
3. Scroll to the Custom Fields section of the Work Item Editor. You should see fields for the title and
description of the target language.
4. Update the translation fields with your translation text and click Save.
When the project is configured for multi-language Work Items, a menu item Switch Language appears
under the menu of the The Document Editor. You can choose any of the configured languages from
this menu.
When you choose a language, the translation of the Work Item titles and descriptions replaces the
previously selected language. Several points are important to remember when viewing translations in a
Document:
• Translated text is read-only. You can, however, edit Work Items in the Work Item Properties sidebar.
• You can print the translated document or export it to PDF so that title and/or description is translated
in the output. PDF export can be configured so that a translated language is written into header and/or
footer when the translated Document is exported.
• History is translated, but translation does not appear in historical comparisons.
• If a translated title or description field is not found when you switch the language, then the content of
the default language field is shown.
Warning
When opening a Document in the read-only translated view, all Work Items contained in the Document
are loaded. If there are many Work Items, it can take some time for the Document to open. This
differs from the normal view, in which large Documents with many Work Items open quickly due to a
background process that loads Work Items as needed as the user scrolls (assuming that the background
processing is enabled in the system configuration).
Voting
If voting is enabled by the Polarion administrator, you can cast a vote for a Work Item. When many people
vote for an item, project managers may decide to increase the priority.
When voting is enabled, the Vote item appears under Actions in the Work Item Editor toolbar. To
vote, just click the menu item.
You can also Vote by scrolling to the Votes section of the Work Item, and adding your name or the names
of other users who vote for this Work Item.
1. Start typing in the name of the person you want to add as Voter, then select them from the list. You
can add multiple Voters at the same time, however, only people with a project-related role are listed.
2. Click Save.
Note
When using Bulk Edit to set Voters for multiple Work Items, only those users are listed that have a
project-related role for all projects of the selected Work Items.
If you vote for a Work Item by mistake, or change your mind later, you can easily remove your vote.
After you have voted for a Work Item, the Vote item no longer appears in the Actions menu, but is
replaced by the Remove Vote item. Just click Remove Vote to remove your vote from the Work Item, or
delete your name from the Votes section.
The Documents and Pages topic provides access to project artifacts such as specification documents,
reports, and informational content. You can access and create the following types of artifacts:
• LiveDocs, referred to in Help as Documents, are special document-like containers for both free-form
text and granular Work Items. For example, in a requirements specification Document you can mark
content elements as Requirement Work Items that can be linked for traceability, workflow controlled,
assigned, planned, scheduled, reported, and managed throughout the artifact lifecycle. Documents
provide an ideal interface for document-oriented and nontechnical authors of specifications.
• Pages contain information that does not need to be tracked and workflow-controlled through a
process as Work Items.
◦ LiveReport Pages are intended for building reports visually using a catalog of Widgets, which
enable nontechnical users to build robust online reports that retrieve, aggregate, and render
information from one or more projects, or an entire repository.
◦ Info Pages enable you to create general information such as internal documentation, guidelines,
meeting notes, preliminary specifications, etc. The content can have rich text formatting, and include
images, tables, and more.
Tip
Widgets are available with both types of Pages, and work the same way in both. The default layouts
differ slightly to facilitate the use cases, but you can build reports or purely informational pages using
either type, according to your own preference.
• Classic Wiki pages use Polarion's legacy free-form content management technology. Content for
these pages is implemented using Wiki mark-up language, and can include Velocity scripts, Javascript,
and HTML.
Caution
Classic Wiki pages are currently supported for backward-compatibility with existing Wiki pages
created prior to Polarion version 2015. That version introduced Pages, which are intended to replace
Classic Wiki, which will eventually be phased out of the platform. You should use Pages for all new
reports and information pages, and plan to reconstruct any reports and information pages you will need
in the long term using LiveReport and Info Pages.
Polarion provides fine-grained access control in the Administration area. Administrators can control users'
access to Documents, Pages, Work Items, and even Work Item data fields. You may be able to view some
types of content, but not modify it. If you find you cannot view or modify information that you need,
discuss your user permissions with your team leader or Polarion administrator.
Test Runs
The Test Runs topic provides access to Test Runs and Test Run templates.
The Test Runs page has two parts. The top pane provides a table of existing Test Runs. It also provides a
toolbar enabling you to:
Clicking any Test Run selects it in the top pane, and loads the detail of the selected Test Run in the bottom
pane.
Click Properties to view Test Run properties, including Test Parameters defined in Test Runs. .
• Click Actions Customize Test Run Page to edit the Test Run page.
• Click Actions Select Test Cases to select the Test Cases to be executed for the Test Run.
For more information, see Select Test Cases.
• Click Actions Save As Template to save the current Test Run as a template on which
to base other Test Runs. If you are viewing the page of a Test Run Template, you can create another
• Click Actions Export to PDF to export the selected Test Run detail to PDF.
• Click Actions Print to print the selected Test Run detail using an available printing device.
You can delete multiple Test Runs by first checking the boxes on relevant rows in the Test Runs table.
When multiple Test Runs are selected, a button appears in the lower pane which will delete all the
selected Test Runs in a single operation.
• Displays information about the status of the Test Run (passed or failed).
• Provides links to passed and failed Test Cases, errors, and executed Test Cases
• Provides information about the test environment and build tested, including a link to that build.
• Summarizes and links to other tests related to the same build, if any.
• Lists problems found during execution of the Test Run, if any.
• Provides access to the Test Run's history.
• Provides access to any Attachments. For example, if the Test Run comprises a set of JUnit tests, a
document containing the specifications for those tests might be attached.
The Test Runs page is one of several features related to Test Management. These features are covered
elsewhere in the documentation.
• If you are a user of Test Management features, please see: Polarion for Testing and Quality Assurance.
• If you are an administrator needing to configure Test Management, please see: Configure Testing.
Related Topics
Project Baselines
Project Baselines capture and preserve the state of your project at some point in time. Baselines are
typically created for major development milestones and for releases. It is possible to generate comparison
reports that compare two baselines and report on the changes that took place between the earlier and the
later baseline.
The Baselines topic appears in the Navigation pane when a project is open. (The topic is hidden when
working in the Repository scope.)
Tip
• You can also create Collection and Document baselines.
• You can query for all baseline types.
The Baseline Time Machine feature lets users with a supporting license browse any baseline as if it were
the current project state. All artifacts appear in the state they were when the baseline was created, and
queries and reports retrieve only information from the baseline.
You can create a new Project Baseline any time you deem it necessary. Your team or company may have a
policy that specifies when these baselines must be captured. Basically, you should create a Project Baseline
whenever the project reaches some state that might need to be reviewed at some later time. If it turns
out you really don't need some baselines, you can always delete them. You must have permissions for any
baseline-related activity you want to do: creating, modifying, viewing, reporting, etc.
Procedure
1. Open the Project for which you want to create a new Project Baseline.
3. Click New in the page toolbar. The Create New Baseline dialog box appears.
4. Enter a name for the baseline in the Name field. This name will uniquely identify the baseline.
5. Select a revision to associate with the baseline you are creating in one of these ways:
• In the Revision field, select a repository revision. The head revision is the default. It captures the
current head revision of the project, with all artifacts, as of the moment the system creates the
new baseline.
• In the Revision field, select Specific. Use the Revision Picker dialog box to select the desired
revision.
6. In the Description field, enter some descriptive text so that others can understand the nature of this
baseline later to see if they want to use it in a comparison report.
7. Click Finish to create the new Project Baseline. It now appears as a row in the Baselines table.
You can generate an on-screen printable report that compares two or more Project Baselines to each
other, or any Project Baseline to the head/current revision.
Procedure
The Baseline comparison report job launches. You can check the status of the job in the Monitor topic.
When the report generation job is finished, a row is added to the table of reports in the Comparison
Reports section of the Baselines page. This section is hidden by default. Click Show Comparison Reports
to reveal or re-hide the section. The Actions column provides two actions for the generated report:
Remove and Show Report.
Note
When using a QA license, an ALM or a Requirements license must be present on the server to be able
to view these reports.
The selected Baseline comparison report displays as a modal dialog after you click the Show Report action
in the table of generated reports. The report contains several sections:
Tip
You can expand and collapse each section using the icon at the right-hand edge of its title bar.
It is possible to modify the name and/or description of an existing Project Baseline. It is not possible to
alter the artifacts captured in Project Baselines.
Procedure
Note
When using a QA license, an ALM or a Requirements license must be present on the server to be able
to view Baseline information.
The Baselines Time Machine feature is so-named because it enables you to go back in time and browse,
search, view, or run reports in a Project Baseline just as if the baseline were the current project state.
Unlike in the project's current state, in a Project Baseline, no artifacts can be changed, and current artifacts
that did not exist at the time the baseline was created do not appear when browsing, and will not be found
by searches or report queries.
Procedure
1. Locate the baseline you want to explore on the Baselines page (Navigation Baselines).
2. Click on the name of the Project Baseline in the Name column.
To exit the baseline and return to the current project state, click the closer on the baseline banner in
Navigation
Note
You can query both Document and Project baselines.
Builds
Note
This feature is also available in Polarion Requirements, but it is hidden in the default configuration.
The topic can be shown in Navigation by changing the Navigation topics configuration. For more
information, see: Configure Interface Views.
Scope(s): Project
The Builds topic of Navigation enables you to access the current and recent builds of any project. You
can find information about the build job(s), create a new build, and access the build results.
The Builds page has two parts. The top half shows a table of recent builds with some basic information
about each build listed. It also provides the New icon for launching a new build, and the Refresh
button which refreshes the page with any new builds that may have been launched since you accessed the
Builds topic.
The lower half provides information about the build currently selected in the top half of the page. The
Build Results section provides access to whatever artifacts the build is configured to generate (often files
distribution, installation, etc.) There are also links that provide access to the build log and base directory.
The Builds topic helps you see build results from Polarion's build-management features.
The Quality topic provides dashboards with key statistics and results of audits and metrics that can be
of interest to QA managers and teams. The information is live based on the actual state of work on the
projects that feed data into the dashboard.
Caution
The Quality topic is deprecated and scheduled for removal.
• Global: Statistics are rolled up for all projects managed with Polarion to provide a high-level view of the
current state of quality across your entire organization. To access this scope, open the repository.
• Project Group: Statistics are rolled up for all projects in a selected project group (which corresponds to
a folder in the repository). This gives you a high-level overview of overall quality for all projects in the
group. To access this scope, open the desired project group. Then select the Quality topic in the
Navigation pane.
• Project: Statistics are rolled up for a currently open project to provide a picture of the current state of
the project's quality. To access this scope, open the desired project, then select the Quality topic in
the Navigation pane.
Links in the dashboard for a broader scope enable you to drill down to the narrower scope(s), and into
different projects.
For project groups and repositories, the dashboard displays a score with a radar chart resulting from the
Process Audit (processaudit) calculation. Data are aggregated from child projects and project groups.
There is also a table listing scores for individual disciplines of the child projects and project groups.
In the project scope, the Quality topic has several sub-topics which load dashboards with different
information about the current level of quality in the project. This information includes quality audits and
metrics.
Process dashboard
Scope: Project
This dashboard reports statistics about compliance with a process. The data are the result of a Process
Audit analysis calculation ( processaudit).
Caution
The Quality topic is deprecated and scheduled for removal.
The dashboard contains a radar chart and a table showing project score (a percentage rating, 0% to 100%)
in several "disciplines" as measured by Process Audit: Release Planning, Iteration Planning, Schedule
Control, Quality Control, and Process Organization. A total score is also displayed, calculated as the
arithmetical mean value of individual scores.
In addition to statistical information, this dashboard provides detailed embedded knowledge about the
process. For every "discipline" there is a detail table with list of rules and scores. You can click on a rule
and see a page with details about meaning of the rule, violations found, how to fix non-compliance, and
configuration possibilities.
You can configure some aspects of this dashboard. See: Process Quality Report.
Scope: Project
The dashboard in the Work Items topic provides some key metrics and statistics about the current state of
Work Items in the currently selected project. It shows such things as counts of unresolved and unassigned
Work Items. The Quality Audit metric in the Metrics portlet can be of interest for quality assurance teams
and managers.
Caution
The Quality topic is deprecated and scheduled for removal.
Work Item metrics and statistics are calculated by the trackeranalysis calculation. It is possible to
configure which metrics and statics are displayed, their labels, and also layout of the dashboard page. For
information, see Work Item Quality Report.
Testing dashboard
This dashboard provides a view on the current state of unit test coverage and success ratio of unit tests.
It also provides drill-down links to details about coverage and to your unit tests. It shows unit test success
ratio and coverage for Maven artifacts with Java sources and tests. The detailed Maven unit test and
coverage reports are linked.
Caution
The Quality topic is deprecated and scheduled for removal.
Data shown in this topic are updated either during the Process Audit calculation (processaudit) or
when the artifact is built using the option Update reports together with the build.
CMMI dashboard
Scope: Project
This dashboard is of interest if your organization implements compliance with the CMMI Maturity model.
Using actual data about the status of a project, it reflects the current level of compliance with all the
indicators defined by CMMI. The dashboard can help organizations learn about CMMI, as all the points for
Level 3 compliance are shown in the dashboard.
Caution
The Quality topic is deprecated and scheduled for removal.
Reports
About reports
Note
This feature is available in PolarionRequirements, but it is hidden in the default configuration. The topic
can be shown in Navigation by changing the Navigation topics configuration. For more information,
see Configure Interface Views.
Scope: Project
The Reports topic provides access to a number of reports related to project source code, and enables
you to explicitly launch report calculation.
• Maven Site
• Unit Test Coverage
• Unit Tests
• Javadoc
• XRef
Maven site
This sub-topic provides access to the latest update of any Maven Site build artifacts of the project. You can
use the Calculate Report to explicitly invoke calculation of the report to get an up-to-the-minute version.
The Maven Site page contains a list of build artifacts, if any have been configured for the project. (See
Basic Build Management for information). You can drill down into the generated Maven reports for any
listed build artifact by clicking on its name. The following reports are generated:
Click on the name of any of these reports to drill down into the content.
This sub-topic provides access to the latest update of the unit test coverage report, which provides
information on how much of the project source code is covered by unit tests. You can use the Calculate
Report to explicitly invoke calculation of the report to get an up-to-the-minute version.
The Unit Test Coverage page contains a list of build artifacts, if any have been configured for the project.
See Basic Build Management for information. You can drill down into the generated code coverage
reports for any listed build artifact by clicking on its name. The report appears in three frames, with various
links that drill down into specific packages or classes, for example.
Unit Tests
This sub-topic provides access to the latest update of the unit tests report, which provides information
about and access to the project's unit tests. You can use the Calculate Report to explicitly invoke
calculation of the report to get an up-to-the-minute version.
The Unit Tests page contains a list of build artifacts, if any have been configured for the project. See Basic
Build Management for information. You can drill down into the generated unit tests report for any listed
build artifact by clicking on its name. The report is built and formatted by Maven (Surefire report).
Javadoc
This sub-topic provides access to the latest update of the project's Javadoc (for projects implemented in
Java). You can use the Calculate Report to explicitly invoke calculation of the report to get an up-to-the-
minute version.
The Javadoc page contains a list of build artifacts, if any have been configured for the project. See Basic
Build Management for information. You can drill down into the generated Javadoc for any listed build
artifact by clicking on its name.
Xref
This sub-topic provides access to the latest update of the project's source code Xref report. You can use the
Calculate Report to explicitly invoke calculation of the report to get an up-to-the-minute version.
The Xref page contains a list of build artifacts, if any have been configured for the project. See Basic Build
Management for information. You can drill down into the generated Javadoc for any listed build artifact
by clicking on its name. The generated report is a framed, cross-linked HTML report of the project source
code. You can look at specific packages to see the classes and drill down into the actual source code of any
class. The access is read-only. You cannot modify any source code.
Monitor
Jobs are background processes which the server executes. Updating a dashboard, or running a build
are examples of jobs. The Monitor topic provides access to information about currently-running and
scheduled jobs. Users with the required permissions can schedule jobs and explicitly launch jobs.
Scheduling and running jobs are, for the most part, a topic for administrators. However, there may be
times when, as an end user, you need to check the status or outcome of some job. You can do that in the
Monitor topic. The topic is available when working in a project or in the global (Repository) scope.
Jobs pane
Jobs pane of the Monitor page shows any currently-running jobs and various details such as when it was
started, and the current status.
For example, if you click the Update link of some dashboard and go to the Monitor topic, you see the
job in the Jobs pane. The Status column indicated whan a job is finished, and you can remove the job by
clicking Remove Finished Jobs, which is enabled on completion of the selected job.
Warning
Jobs consume system resources and can significantly slow the system for other users, depending on the
type and scope of the job. It's a good idea to bear this in mind when deciding to explicitly run a job.
The Scheduled Jobs pane displays the jobs currently scheduled by the system configuration. If you have
permission, you can select one or more jobs in the list and run them immediately. The preceding warning
about jobs and system resources applies here too. For more information on scheduled jobs, see: Configure
the Scheduler.
Repository Browser
The Repository Browser topic provides access to the integrated Subversion repository and provides
some basic client functionality including browsing, downloading, and committing locally changed
resources.
The Repository Browser topic does not appear in Navigation in the Default view.
The Repository Browser topic is only available in the Admin view by default, and only for users with
the global Administrator role.
System administrators must do the following to enable the Repository Browser of other Global or
Project roles:
• Configure Interface Views so that the Repository Browser is visible under the target scope (
Project or Global). Make sure that repository_browser is present in the topics list for that view.
• Assign a Role under Limited to Roles to ensure that the Repository Browser is only visible for
selected to users.
• Give users that you want the Repository Browser visible for the configured limited role under
User Management.
Note
Tip
With Polarion 2304 and later releases, we advise System Administrators to remove the
repository_browser topic ID from the template project extensions before importing items into
production servers. This is necessary to ensure that repository browser access is limited to assigned
roles.
Also see Define a new interface view and Configure Navigation topics for more information.
By default you begin browsing in Polarion's main internal repository, the root folder, and the Head revision.
The Path at the top of the page shows you your current location at all times. All folders in the Path are
hyperlinks. Clicking on a folder name in the Path takes you directly into that folder.
At the right side of the Path bar are controls that enable you to select the Trunk, branches, or tags, select a
revision to browse, and navigate up one folder in the Path.
The table in the Info tab lists the content of the current repository folder, which appears as the last
element in the Path. Content is either folders or files. Each content type is distinguished by a folder or file
icon.
To drill down into a folder or file, click the folder name in the Name column.
• Click the Revision List icon in the Info bar, and select a revision in the list of revisions that appears.
• Click Browse in the Path bar (right side of page), and in the Go to path screen, enter the number of the
revision you want to browse.
Compare revisions
Procedure
1. Browse into the file for which you want to compare revisions.
Repository operations
Using the Repository Browser you can add folders, directories, and files, commit a locally changed file,
delete existing content, or download a file or a directory as a Zip file. Use the respective icons that appear
in the Info tab.
To delete content, select the check box located at the far left of an element's row in the Info table. Select
all elements you want to delete, and click Delete selected elements.
Tip
You can use almost any Subversion client to access the Polarionrepository from outside the portal.
You can access the entire repository or just certain projects. For this you need the URL of the portal
repository and/or project folders within it. You must have access permission for the repository.
By default, the repository root URL is shown in the Project Group Overview in the Repository Home
topic. The URL for a project is shown by default in the Project Overview section of project Home pages.
(Home pages may be customized from the default and may either show the repository URL elsewhere, or
not at all. Consult your portal or project administrator if necessary.)
Procedure
1. Using links in Info and/or Path, navigate to the folder you want to download as a local copy.
2. In the Info tab, click Download current directory as a zip.
3. If necessary, move the downloaded Zip file from your default download location to some other
location and unzip it.
Caution
The Repository Browser downloads only files. It does not download any Subversion metadata or
control files. Consequently, the download is not a true SVN working copy that can be used with an
external client. The Repository Browser is not intended as a full-featured SVN client. If you need full
functionality, you should obtain and use one of the many available Subversion client applications.
Procedure
1. Navigate to the head revision of the file in the Repository Browser, and open it so that you are viewing
the file content.
2. In the Info tab, click Download.
3. If necessary, move the downloaded file from your default download location to some other location.
Procedure
1. Navigate to the head revision of the file in the Repository Browser, and open it so that you are viewing
the file content.
2. In the Info tab, click Commit.
3. On the Commit File page, click Choose File, and then select your local copy of the file.
4. Enter a commit message in the Comment field and click OK.
5. Click OK on the Change confirmation page to complete the commit operation.
Add a directory
The Repository Browser enables your to add new directories in the repository.
Procedure
1. In the table of resources, drill down into the directory that will be the parent of the directory you will
add.
2. In the Info tab, click Add directory.
3. Enter a name for the new directory. Enter a comment to replace the default comment, and then click
OK.
4. In the Change confirmation panel, click OK to complete the operation.
Procedure
1. Using links in Info and/or Path, navigate into the folder in which you want to add a new file.
2. In Info, click Add file.
3. Click Choose File, and in your system's file selection dialog box, navigate to and select the local file
you wish to add.
4. (Optional) Enter a comment to replace the default comment, and then click OK.
5. In the Change confirmation panel, click OK to complete the operation.
Note
You can only add one file at a time using the Repository Browser. If you need to add many files, use
an external SVN client that has features for adding multiple files at once.
Procedure
1. In the table of resources, drill down into the folder containing the file(s) you want to delete.
2. Select the check box on the row of the file(s) to be deleted.
3. In the Info tab, click Delete selected elements.
4. Add a comment and click OK.
5. In the Change confirmation panel, click OK to complete the operation.
Activity Stream
The Activity Stream feature is similar to the news feed feature found on social media websites. It displays
a stream of activities of various kinds, or Sources, as they occur in real time on the Polarion portal.
Activity Sources include such objects as Work Items, Plans, Builds, and Test Runs. For a complete listing
see Activity Sources and Types, later in this topic.
Some portal pages, such as the portal Home page, and users' My Polarion pages, contain the Activity
Stream by default. Authors of Pages can use the Activity Stream widget, and configure it to stream all,
or a subset of Activities occurring in the scope of a specific project, or the entire portal. For example,
the widget in a Live Report Page in a project might be configured show Activities taking place on
Work Items in that project that relate to defects. Another instance of the widget on the Page might show
Activities generated by project Plans. Legacy Classic Wiki pages can implement the Activity Stream with
the {activity-stream} macro.
Each Activity in the stream displays basic summary information including the name and avatar of the user
who triggered the Activity, and when the activity took place. Hovering over an Activity highlights it, and
clicking on it (or on the Show More link, if present) expands the activity to show more detail. Each Activity
contains a link to the Activity Source (Work Item, Build, etc.) that opens the source item.
The Activity Stream refreshes when the page containing it loads or reloads. You can explicitly refresh the
stream to see new activities using the
You can enter a search term in the field provided at the top of the Activity Stream to filter the Activities
listed. You can search by specific words, by Activity Source and type, or a combination.
The simplest and most intuitive way to search the Activity Stream is to enter some word or words. The
results will show all Activities that contain the search words, if any. If the search string is a user name,
the results contain both activities generated by the matching user, and activities containing that name
somewhere in the content.
If you enter multiple words, the search logic is AND. For example, if you search for smith language,
the logic is smith AND language. The results will contain Activities generated by any user named
Smith, Activities mentioning "smith" , and activities mentioning "language", both case insensitive. You
could explicitly specify the AND operator, but it is not necessary. If you want to exclude some term, you can
precede it with the operator AND NOT. For example: smith AND NOT language. If you enter multiple
words, and you want results with one or the other, you can enter the OR operator: smith OR language.
The Activity Stream has the following Activity Sources, and Types within the sources. If no Type is
specified in searches, all Types are shown in the stream.
You can search for a specific Activity Source and Type by entering a query in this format: sourceId:
[ID]. For example, you could filter for Activities around Work Items with: sourceId:workitems.
You can refine the filter by including the Type parameter in the filter search string. For example, you could
filter for Activities around updated Work Items with: sourceId:workitems AND type:updated.
You can use valid values for an Activity Type like updated or created to search for Activities having a
specific Activity Type. You can use AND/OR logic to search on multiple Types, or keywords and Types. For
example., you can search for user names and Activities having the created type: sourceId:workitems
AND type:created AND aUsername1 OR Username2
Polarion Documents (LiveDocs) are as easy to use as your favorite desktop word processor but let you
integrate Work Items, Create Document Baselines, add them to Collections and more.
Your ability to work with LiveDocs is controlled by permissions granted to your user role in projects.
You may have different roles in different projects, and your access level may vary according to your role.
For example, you may be able to create new Documents in one project, but not in another project. Should
you find that some feature seems to be missing, or you cannot perform some operation, check your
permissions with the project administrator.
Business User
Create and work with Documents. Create, organize, browse or search for LiveDocs.
Integrate Work Items into your Document. Add multiple Work Item types, Mark content as a
Work Item, structure Document Work Items and
copy and paste Work Items.
Creating a new Document in your Polarion portal is as simple as creating a new document in your
favorite word processor application. Documents for a project are stored in one or more spaces under
the Documents and Pages topic in Navigation. You can locate them easily either by browsing the
Documents in Navigation, or using the Navigation pane's filter box, which provides incremental search of
your project content.
• Create a new empty Document in the Polarion portal using the New Document feature.
• Create a new Document by importing an existing Microsoft Office Word document, using the Word
Import feature.
Spaces and Subspaces in Polarion are like folders and subfolders on your operating system.
When creating documents in Polarion for the first time, it's a good idea to plan out how you would like
to organize them beforehand. Unlike Word documents, Live Documents and Live Reports are
integrated with a vast array of possible widgets, potentially thousands of Work Items, and in the case of
Live Documents, a powerful version history.
Quick Links:
Tip
• Administrators can configure Quick Create so users can create Spaces right from the Navigation
Header.
• Plan and create your Space and Subspace hierarchy before creating documents to avoid any
move restrictions.
Using the icon allows users to copy the Space Home Page link with its Title as the link's label.
When navigating Spaces, the path (Project Spaces Subspaces Document name)
appear in the Navigation Header.
Warning
Permissions change when creating a new Subspace within a Space. If you create a Subspace
within a Space, or move a Space/Subspace from another Space, they do not inherit the Subversion
repository's restrictions, or permissions from their new parent. If you want to restrict access to a newly
created Subspace, you need to work with an administrator to remove the SVN access rights and create
a custom rule for permissions (see Configure user Permissions: Define permissions for Artifact Sets).
Note
You can move LiveDoc Documents once they're created, but you cannot move Live Report, Info or
Classic Wiki pages.
You can create five levels of nested Subspaces and up to 250 artifacts within each of them.
Tip
Plan and create your Space and Subspace hierarchy before creating Documents to avoid any
move restrictions
Note
Hierarchical Spaces created in the Polarion do not actually create physical nested folders within the
repository.
Procedure
• If you clicked on an existing Space or Subspace, click Expand Tools at the top, then
and click .
• If you clicked on an existing, top level, Space, click Expand Tools at the top, then and click
4. Enter a Space Title, a Space Name and select the Parent Space that you would like the new
Space to appear in.
If you've already created a Subspace within a Space, then the hierarchy appears within the list
control.
5. Click Create.
6. Now when you create a new Live Document, Live Report, Info Page, or Classic Wiki Page , you can
select any Space or Subspace in the Space list.
You can rename Spaces or Subspaces from the Documents & Pages in Navigation.
Procedure
5. Click Save.
6. The updated name appears in Navigation.
You can delete Spaces or Subspaces if you have permission to do so, but be careful.
Warning
If you delete a Space, any Documents or Subspaces within it are also deleted, and cannot be
restored.
Delete a Space
Procedure
Delete a Subspace
Procedure
1. Click the Index of the Space that contains the Subspaces you want to delete.
You can save Spaces or Subspaces as Shortcuts to easily access them from Navigation.
Procedure
1. Click the name of the Space or Subspace that you want to save as a shortcut.
4. Select where you want the shortcut to appear in the Type drop-down.
a. Select Favorite if you want it to appear favorite section in Navigation.
b. Select User, Project or Global to have it appear in the respective folder in Navigation.
Tip
• You can modify the position of the Shortcut, and you can remove it at any time.
• Filtering also works in Space/Subspace hierarchies added as favorites.
Document Baselines
Document Baselines let you mark and label a specific Document save (revision) in a Document's history.
Tip
Select Show only baselines to hide normal revisions and only show Document and Project baselines.
This setting is remembered for the current user across all Documents.
When you're looking at a Document Baseline, a large blue button appears at the top of the document.
Hold the mouse over the button to view the Document Baseline's details.
Click on the blue button to view and edit the baseline's details.
The name that appears in the Document's history beside the revision number. You cannot leave this
blank.
◦
◦ The Document name link.
◦ Open Document
• Edit or add a Description. Only visible on this detail screen.
• Click to view a history of changes and who made them for the Name and Description fields.
Tip
Administrators can configure Polarion so that a Document Baseline is automatically created by a
Document worfklow transition.
Procedure
5. Enter a Name.
6. (Optional) Enter a Description.
Will appear in the Description field of the Document Baseline detail screen.
7. Click Create.
A Baseline successfully created message appears.
8. Click OK to open to the Document in the Baselined version or Continue to HEAD to open the most
recent version.
9. (Optional) Click on the top right to view the Document's history and your new Document
Baseline.
10. (Optional) Click Show beside your Document Baseline to view it in the Document Editor.
Note
You can query both Document and Project baselines.
You can create a Document baseline anytime to mark a specific milestone, like a release or version.
Tip
Administrators can configure Polarion so that a Document Baseline is automatically created by a
Document worfklow transition.
Procedure
5. Enter a Name.
6. (Optional) Enter a Description.
Will appear in the Description field of the Document Baseline detail screen.
7. Click Create.
A Baseline successfully created message appears.
8. Click OK to open to the Document in the Baselined version or Continue to HEAD to open the most
recent version.
Your new Document Baseline now appears in the Document's history.
9. (Optional) Click on the top right to view the Document's history and your new Document
Baseline.
10. (Optional) Click Show beside your Document Baseline to view it in the Document Editor.
Note
You can query both Document and Project baselines.
Create a new empty Document when you want to create new content such as specifications, or any
type of document that contains Work Items, and you do not already have the content in a Microsoft Word
document from which to import it.
When you create a new Document, the Document Editor opens enabling you to write and format
the content. The most current saved state of the Document is online at all times. You can share the
Document's URL with other Polarion users, and other users who have the necessary permissions to access
the project and the Document can collaborate on the content. You can also use the Round-trip for
Microsoft Word feature to share the Document with external stakeholders who do not have access to the
Document in your Polarion portal.
Tip
Administrators can configure Quick Create so users can create Documents right from the Navigation
Header.
Procedure
2. In Navigation, click Documents and Pages. The topic's home page opens.
3. In the toolbar at the top, click the icon and select LiveDoc Document.
The Create LiveDoc Document dialog box appears.
4. Fill in the required fields and edit the default optional fields.
• Title: Specify a human-readable Document title. Characters other than ASCII may be used.
• Name (ID): Specify an identifier (referred to as ID) unique to the current project and space. Used
by the system for indexing and other purposes. Use only ASCII characters in IDs.
• Type: Choose from a list of available Document types. This field is present only if Document
Types are configured for the project.
• Space: Select the Space or Subspace where the new Document is located once it has been
created.
• Work Item Type: Select the main type of Work Item the new Document should contain. You can
add more types after the Document is created. The list control contains the Work Item types
defined in your project configuration. You must select one of the listed types — only administrators
can create new types.
• Link Role: Select the default link role that should be applied to hierarchically structured Work
Items in the new Document.
For example, if you split a paragraph marked as a requirement so you have two separate
requirements, and you then indent the second paragraph, this option controls what relationship is
applied between the indented requirement paragraph and the preceding requirement paragraph.
Typically the indented paragraph is a child of the preceding, so the default selection has parent is
what you want.
Note
This is just the default: you can apply any configured link role later on when editing the
Document.
• If you want the Document's headings to have outline numbers, select the Enable Outline
Numbering box and optionally enter a prefix value in the Prefix field.
5. Click OK to create your new Document. .
The new Document loads in the Document Editor ready for editing. Before beginning to work on
the new Document, you may want to check the configuration that controls how the Document
displays Work Items. Click the Work Item type icon in the Document Editor toolbar and choose
Configure. For more information, see Multiple Work Item Types
Tip
When hovering over the Smart Title of a Document in the Navigation Header, a copy icon
appears.
Using the icon allows users to copy the Document link with its Title as the link's label.
Polarion supports the linking of remote data from other tools, like Teamcenter.
• Create links for Work Items or Documents from objects that reside on external OSLC enabled tools.
(Act as a Linked Data consumer.)
• Link Polarion Documentsto objects that reside on external OSLC enabled tools. (Act as a Linked Data
provider.)
This is generally done by creating or selecting a remote object in a so-called delegated UI provided by the
Linked Data provider.
Once Linked Data Friends are configured by an administrator, they appear as an icon in the
Linked Work Items section of a Work Item.
Procedure
6. Select the link's role and click Link External Item (OSLC).
8. Click Allow.
9. Click Select an Existing Item and select an option.
Or Create New Item to create a new item in the external application.
Note
Create New Item launches the external OSLC application in a pop-up window.
The workflow to create a new Item varies depending on the application.
Procedure
1. Select an item from the list on the left. An overview of its details appears on the right.
2. Click OK.
3. The item is linked to the Polarion Document.
You can use the Import from Word feature to convert existing specification content, such as requirements
or test cases, written in a Word document into a Polarion Document.
You can take advantage of Polarion's process automation and management capabilities with the familiarity
of desktop-based office documents.
Importing Microsoft Word documents into Polarion lets your authors create content in a familiar formatting
environment, and you gain additional control over the process, full-lifecycle traceability, transparency, and
team collaboration and communication.
Tip
After a Microsoft Word document is imported, you can always export it back to its original format to
work on it offline, or enable others to do so with the Round-trip for Microsoft Word feature.
You can import existing requirement specifications into Polarion so that Polarion automatically
differentiates between general information and content you want as Requirement Work Items. You
can then track, assign, plan, and manage these Work Items with a workflow and link them for traceability
across functional boundaries like Quality Assurance and Development.
Example
The word must in your document might trigger an action to set a value in the Severity field to must
have or any value defined in the project configuration for that field.
You define Work Item recognition Rules using easy-to-understand graphical controls when you import a
Microsoft Word document into Polarion as a LiveDoc Document.
You can save a set of rules as an Import Configuration that can apply to other documents when you
import them.
You can have multiple Import Configurations for different types of documents.
For example, you might have one set of rules in an Import Configuration you apply only when importing
software requirements specifications, another for functional requirements specifications, and another for
test case specifications.
Microsoft Word documents to be imported must be saved in the *.docx Word Document format.
Tip
If the default paragraph style in a Microsoft Word document is customized, that will not affect its
appearance when imported into Polarion, but the custom styling will still be applied when the document
is exported back into Word for round-trip collaboration.
Tip
While there is no hard limit to the number of Work Items a Document can have, the recommend
best practice is to keep it under five thousand.
This topic explains how to begin importing a Microsoft Word document. Other topics, linked below, explain
how to define rules to automatically recognize Work Items, set severity level and/or other data values from
document content, and then work on the new Document after importing.
Documents can only be imported into an existing project. If you do not yet have a project created for
your Documents, you should read about planning new projects and creating new projects before going
further with Word import. You must have user permissions allowing you to create and save content in the
project where you will import Microsoft Word documents.
Tip
Administrators can configure Quick Create so users can import from Microsoft Word right from the
Navigation Header.
Procedure
1. Open the project into which you want to import your document content.
2. In Navigation, click Documents and Pages. The topic's home page loads in your browser.
4. In the Import section of the Create New dialog, click the link labeled Word Document.
5. In the Configuration list, choose an Import Configuration. If no Import Configurations have been
saved by you or other users, the only item in the list is Default. Using that import configuration you
are able to define Work Item recognition rules and save them as a new Import Configuration later in
the import process. If additional Import Configurations are present in the list, optionally select one
that you know to be applicable for documents of the kind you are importing.
Tip
Import Configurations let you reuse Work Item recognition rules when importing other Microsoft
Word documents. Additional Import Configurations appear in the list only if a user has created
and shared them, or the project template from which the project was instantiated provides some
additional import configuration(s).
The Preview contains a panel where you can optionally specify a name (ID) and title, specify the
Document type, select the destination space, and define and save rules that control the recognition
of portions of the content as Polarion-managed Work Items (see the screenshot in the next section.)
8. In the rules panel, optionally change the default Document name and title in the Name and Title
fields, respectively, at the top of the panel.
9. If your project is configured to support Document types, you can optionally select a different
Document type in the Type field. If no Document types are configured, the field is not present.
10. In the Space list, select the Space where you want the LiveDoc Document to reside.
If you don't want to define automatic Work Item recognition rules at this time, you can remove any existing
rules in the Preview, and check the preview of the Document to make sure that nothing is marked as a
Work Item, and then click the Import button to finish the import process and create the new Document.
You can then work on this document and mark Work Items manually while editing the Polarion document.
If you do want to have content recognized and marked as Work Items on import, you now need to define
Work Item import rules so that Polarion will automatically create Work Items in your new Document when
you complete the import process.
Note
If the project is configured to support Document workflow, then after the import operation, the Status
field of the new LiveDoc Document will be set to the configured initial Status value, and any configured
initial workflow action will be invoked.
For example, if the initial configured Status value is Draft, the new Document will have that status, even
if the source Document was not a draft, but a finished specification.
Polarion can create Work Items based on content elements in a Microsoft Word document according to
Work Item import Rules you specify during the Preview stage of the import process. This topic assumes
that you have successfully initiated import of a Microsoft Word document and are now seeing the
Preview:
Your goal is to have Polarion recognize that some content in the imported document is just general text,
while other content should be recognized as Work Items of some particular type — requirements or test
cases, for example. While the Document is in Preview mode, you can experiment with the Work Item
recognition Rules without actually creating any Work Items in the repository.
Advance Preparation
Before you begin importing Microsoft Word documents, there are several things to set up and to know
about.
• Target project: You should already have a project set up in Polarion, and you should know what Work
Item types are defined in the project's configuration.
• Document types: You should know whether your project configuration defines different types of
Documents. If it does, you will be able to choose the type into which your content is imported. If
not so configured, consider whether you your project should be configured for different Document
types before importing your content.
• Work Item types: You should decide which Work Item type or types you want to create in Polarion
when importing a Microsoft Word document.
• Content to Work Item mapping: you should review your Microsoft Word document and identify what
elements should become Work Items or Work Item attributes such as description after the document is
imported. This is key successful Work Items recognition from your document's content. The next section
discusses how to prepare a document for import to Polarion.
Carefully go through the Microsoft Word document you plan to import and make sure you know what
content should be managed as Work Items in Polarion after import.
• What elements of your document should Polarion recognize and mark as Requirement type Work
Items?
• Should it recognize particular words?
• Should it recognize paragraph or list item styles, or entire sections under headings?
• Should you define simple, complex, or multiple Work Item Rules to achieve your desired recognition?
While you can devise complex, granular strategies, you can achieve a great deal with fairly simple Rules.
Example
Polarion's default import configuration recognizes the words must and should, it will mark paragraphs
containing those words as Requirement Work Items, and it sets the Severity level to must have or
should have accordingly.
• The project configuration must have the Requirement Work Item type and the Severity levels
defined.
This configuration is predefined in project templates that support requirements management.
• If you create a project based on these templates and edit your Microsoft Word document so that only
requirements contain must and should, the default Work Item Ruleis very effective.
Another easy to implement mapping strategy is to make sure all requirements in your Microsoft Word
document have a particular style. For example, you might define paragraph style named Requirement and
apply it to all paragraphs that should be recognized as Requirement type Work Items.
When you import the document, create a Work Item Rule that specifies that elements in the document
with that style applied to them should be recognized as Requirements.
Another mapping approach that is still fairly easy is to define a heading style named something like
Requirement H3 in addition to the paragraph style named Requirement. On import, you can create a
relatively simple Rule with multiple conditions that says to mark content styled Requirement 3 as a Work
Item, and include in the description any following paragraphs styled with the Requirement style.
Suppose that you have a bullet list after a paragraph styled as Requirement, and you also want to include
the list in the Work Item description. To do that, add another condition to the Rule that says to include
paragraphs styled as list items which occur after a Requirement 3 styled heading. This gives you a very
powerful, but still fairly easy-to-define Work Item Rule.
Tip
Remember that in the import Preview, you can experiment with Rules and see what their effect will
be before you actually create any Work Items in the repository. The Rules pane contains the Preview
button in the lower left corner. Clicking that button loads a preview of the Document with the current
Work Item Rules applied as they are currently defined. You can continue experimenting with Work Item
Rules until you are satisfied with the result you see in Preview.
Remember also that you can save Work Item Rules as Import Configurations, which can be used when
importing other Microsoft Word documents with similar characteristics.
A simple Work Item Rule is one using only basic options and specifying one or more conditions. A Rule's
components are like an instruction sentence. For example:0
— after which come one or more conditions: [contains words][words], [has style][style
name], [contains text matching regex][regular expression], to name a few examples of
conditions.
Let us see how to define a simple Work Item Rule with two conditions that will cause paragraphs
anywhere in the imported document to be marked as a Requirement type Work Item if they contain any of
the word shown, or if they are a list item.
Procedure
1. In the Mark paragraphs from field, select the content element or elements of the original document
to which Polarion should apply Rules to recognize Work Items. Select Document to allow Polarion to
apply Work Item recognition Rules to all elements.
2. In the list following the word as, select the type of Work Item to be recognized in the content source.
The list contains the Work Item types defined in the project configuration.
3. On the first conditions line, select a condition from the list of conditions. If your selection requires
more input to complete the condition, an appropriate text, list, or other field will appear on the line.
Fill in the additional information.
4. If you need another condition in this Rule, select it in the list on the second conditions line and as
before, fill in any additional information.
5. If you need more conditions, add new condition lines by clicking the icon. Fill in the data as
needed. If you make a mistake, you can remove any condition line from the Rule by clicking the
icon at the end of the line.
If you need one or more additional Rules to achieve the Work Item recognition you want, you can click the
Add Work Item Rule button near the top of the Rules pane. A new simple Rule is added each time you
click. Repeat the above steps for each simple Rule you add.
Each simple Rule you define can have Advanced options added to it to make it even more robust and
selective. Advanced options are disabled by default. To enable these options for any Rule, select the Show
advanced options check box. The Rule panel expands to show the advanced options.
Advanced options fall into the following categories which appear as labeled sections in the Rules panel:
• Paragraph inclusion conditions: Specify conditions for including paragraphs that follow a content
element marked as a Work Item per the conditions defined in the simple Rule. For example, suppose the
simple Rule specifies that elements styled as Heading 3 are to be recognized as Work Items. You would
probably want the paragraphs that follow the heading included in the Work Item description, so you
can specify one or more conditions under Include next paragraph to the Work Item description. You
might specify paragraphs that have some style, and/or that are list items to include after the heading.
• Actions: Define actions which set the value of Work Item fields when document content is recognized
as a Work Item according to the Rule. Each Rule's Advanced options contain one action by default. If
you don't want it, you can remove it by clicking the X icon in the upper right corner of the action's panel.
If you want more actions, you can click the Add button at the bottom of the Actions section.
Each Action applies to a selected Work Item field of recognized Work Items. Select the field in the Set
field list. Depending on the field selected, a control appears which enables you to set the value of the
selected field. The execute field enables you to specify whether the specified value will be set always, or
conditionally. If conditionally, fields appear enabling you to define one or more conditions in a manner
similar to conditions for other Rule parameters.
• Additional options: Opt to have the first paragraph of any block of content the Rule marks as a Work
Item imported as the title of the recognized Work Item. The first paragraph of such a block might be a
heading. You can also specify which fields, if any, you want to appear at the beginning, and at the end
of recognized Work Items in the LiveDoc Document. You must specify the field ID in Fields at start and
Fields at end. If you want the values of more than one field to appear at the start or end of recognized
Work Items, specify multiple IDs separated by a comma.
Work Items can even be extracted from tables within a Microsoft Word document. You can target all the
tables within a document or select only the sections, even subsections to include.
Tip
Import Rules for content contained in tables may require the use of regular expressions (regex). How
to extract fields from tables is included in the steps below, but see Import Rules for Tables for more
examples.
Multiple Rules can be created to extract different Work Item types such as Requirements or Tasks.
Severity or Priority levels can also be automatically extracted.
In the example below, requirement keywords within a table are detected and assigned different Work Item
severity levels using the advanced table Rule options.
Procedure
1. (Optional) To extract Work Items exclusively from tables within the document, close ( ) the section
Mark paragraph from.
2. Click + Add Work Item Rule and select Mark Tables.
3. Define the scope of the tables to include in the Mark tables from drop-down menu.
(Clicking on Document will apply the Rule to the entire document.)
4. Select whether to invoke the Rule if any or all the conditions are met.
5. Select whether to apply to Rule to Whole Tables or only the Header Rows.
6. Under Import Rows, select a Work Item type in the as list.
Types listed vary depending on the project configuration.
7. Select the Rule's behavior in the drop-down list.
Tip
Mouse over the option to view a tooltip describing what it does.
8. Enter the condition details in the field that appears on the right.
If contains text is selected like the example above, enter the text that the Rule should search for.
Tip
To assign different Work Item attributes to each condition — Severity, for example — rather than
adding it here, create an entirely new Rule by clicking Add after the initial Rule is defined. See
optional step below.
10. Polarionwill automatically detect the target area’s columns and try to match the text to existing Work
Item definitions.
Any column headers that cannot be recognized can be assigned manually or excluded by leaving
them as not selected.
12. (Optional) Click Add then select an option in the Set Field to enter additional Work Item attributes
like Severity or Priority.
(The available options can be customized by administrators.)
13. (Optional) The available options under the To field change depending on what was selected in Set
Field.
In this example, Severity is selected to convert table cells that contain the word should, to
requirements with a severity level of Should Have.
14. (Optional) Specify when the Rule should be implemented in the Execute list. The default is Always.
15. Click Preview to see how the Rule affects the document.
Tip
It is important to understand that the document has not been fully imported yet, and nothing has
been written to the repository.
Clicking Preview displays what the Rule will mark as Work Items when you finally click Import.
This way, you can thoroughly test Rules and Rule combinations without creating, and later having
to delete, unwanted Work Items.
Any table rows that do not have a Work Item Rule applied to them are highlighted in red.
Table rows that contain data that the Rule(s) recognize are converted to work items that appear
below the table.
Detected table data looks like this:
16. Check the Replace Table with Imported Items box to replace the table(s) with the extracted Work
Items.
If left unchecked, the created Work Items will appear directly below the table in which they were
detected.
17. (Optional) Click Add above Replace Table with Imported Items to add another table Rule.
Severity[\s&&[^\t]]*\tLow\t\n
(See Import Rules for Tables for more regular expressions you can use with tables.)
Tip
you can click to the right of + Add Work Item Rule to save the set of Rules for later use.
Procedure
Click Import when you are satisfied from the preview that all the information you want shown as Work
Items is correctly shown.
Once you have defined a Work Item Rule or a set of Rules and run Preview to verify that they cause Work
Items to be marked correctly, you can save your Rules as an Import Configuration that can be reused
when importing similar documents in the future, thereby eliminating the need to specify the same Work
Item Rules again.
Procedure
1. In the Rules pane, click and choose Save. The Save Import Configuration dialog appears.
2. If you are saving Rules to a new configuration, select Create new configuration and enter a
name in the Name field.
3. If you want to save your current Rule definitions to overwrite an existing configuration, select
Update existing configuration, and select which configuration you want to update from
the list of existing configurations.
4. Click Save to save the new or updated configuration. If you saved a new configuration, it now
appears in the list of Import Configurations, which users can select when importing Microsoft Word
documents.
If you or a colleague saved a set of Work Item Rules as an Import Configuration, you can reuse it to import
a document in some instances. The content of the document you are importing must conform to the rules
defined in the Import Configuration so that Work Item content is correctly recognized.
Procedure
1. With the imported Microsoft Word document in Preview mode, click ( ) and choose Load.
2. In the dialog, select the Import Configuration whose Work Item recognition Rules you want to reuse
for the current import operation.
3. Optionally, click the Preview button and check the document preview to verify that the document's
Work Items are marked as expected.
4. Click the Import button to import the Microsoft Word document reusing the selected Import
Configuration.
Having the Work Item recognition process set the severity level of recognized Work Items automatically is
commonly-needed, and is just one example of the actions that can be invoked and applied to recognized
Work Items during Work Item recognition. You can specify this in the Actions section of the Advanced
options of a Work Item Rule. There, you can select the Severity field, and specify the conditions for
setting a value for the field when a Work Item is recognized according to the rule. For more information,
see Define Advanced Option Rules.
Table of contents
The import feature also imports Table of Contents from the source document. Keep the following points in
mind:
• Outline numbering is turned on by default, and the TOC of the resulting Document will contain
outline numbers in the TOC.
• If the source document contains a table of contents, a table of contents will be generated in the
resulting Document during import. A manual TOC is replaced by an automatically generated and
updated TOC in the Document. Up to five heading levels are recognized and rendered in the TOC of
the Document. Properties of the original TOC are saved and used in any subsequent Word Round-trip
export.
• If the source document contains a TOC, the import preview shows how it will look in the Document
after import. The TOC preview is updated when the import preview is updated. TOC items in the import
preview are not clickable.
• Headings that are recognized as Work Items do not appear in the Document TOC, in both import
preview and the Document. If the source document contained a TOC but all headings are recognized as
Work Items, then the Document's TOC is initially empty.
Polarion can display OLE Object thumbnails during import. However, some additional third-party image
converter software must be installed and configured by an administrator before you can import such
documents. Information for administrators is provided in the Configure OLE Object Support topic.
Unsupported content
If the source document contains images or other content in formats not supported by the import
from Microsoft Word and image conversion features, the document is imported into Polarion without
the unsupported content. If your project administrator configures the wordImport.ignore.[CLASS]
system property for the content types in your Microsoft Word documents, a placeholder image and/or text
informing you of the omission is inserted into the Polarion Document at the same point where the
original, unsupported content was in the original document.
ReqIF Import/Export
In Polarion, you can import ReqIF files into Polarion Documents, and export Documents to a ReqIF file
using the ReqIF Round-trip feature. This feature can be used to exchange requirements between different
Polarion servers as well as between external tools and systems.
Polarion currently supports ReqIF versions 1.0.1 and 1.1, and RIF versions 1.1a and 1.2. The following file
types are supported:
Note
ImageMagick must be installed and configured to see the thumbnails of imported OLE Objects.
Tip
• When Polarion Cross References are exported to ReqIF:
Note
Currently, you cannot view Microsoft Visio file previews, but it will be possible in future Polarion releases.
If you've configured ImageMagick correctly, but OLE previews display an error image, it may be a caching
issue.
Procedure
Warning
The following are not supported for ReqIF:
• Tables
• Mathematical formulas are not supported for ReqIF import/export.
• Attachments (including Document attachments) are only exported if they are referenced in a rich-text
field of a Work Item within the same scope. Exported Document attachments referenced in a Work
Item rich text field will belong to that Work Item when imported to a new Document and do not
become Document attachments again.
You can import ReqIF/RIF files one at a time or several at once and they may contain one or multiple
specifications. If a file contains multiple specifications, you map them to different Polarion Documents.
When importing a ReqIF file for the first time, a Polarion Document is created for each specification in
the ReqIF file. Subsequent imports of the same ReqIF file into the same Space automatically map to the
respective Polarion Documents and its content is updated and synchronized with the content of the ReqIF
file.
Required Permissions
• The project_user role together with permissions to create Modules, modify fields and the content of
modules, create and modify Work Items and manage Documents are required.
<grant permission="persistence.object.Module.create"/>
<grant permission="persistence.object.Module.modifyFields"/>
<grant permission="persistence.object.Module.modifyContent"/>
<grant permission="persistence.object.WorkItem.create"/>
<grant permission="persistence.object.WorkItem.modify"/>
<grant permission="persistence.object.Module.manageDocument"/>
• Along with the above permissions, access to the /modules and /.polarion/reqif folders are also required
for the importer to work.
If a ReqIf file contains multiple specifications and you import it into Polarion, links between the Work Items
in the different modules can also be imported.
• When linking items via ReqIF, the ReqIF Relations attribute should be mapped to Linked Work Items.
An object that's only in the first ReqIF An object that's only in the second ReqIF
specification. specification.
Tip
Administrators can configure Quick Create so users can import a ReqIF file right from the Navigation
Header.
Procedure
1. Open the project that should host the imported requirements. Be sure that you have the necessary
permissions above to create new Documents.
2. In Navigation, expand Documents and Pages and expand the node of the Space that you want
to import to, or create a new Space, and select Index.
6. Wait for the initial import to finish. If the file is large the process can take a while.
7. When the Import Document page appears, select the specification(s) you want to import. Map all
selected specifications in the ReqIF file to a Space (the current Space is used by default), and a
Document.
Tip
You can auto-map a ReqIF file with several documents.
If you import an updated version of a ReqIF document that was previously imported, the target
Document value will be pre-filled and can't be changed.
Note
To use a custom field as the Flag field, you must define it for every Work Item to make it selectable
as the Flag field.
The Document's Delete options (Select System and Custom fields can be
Name. Ignore when importing a created for the following types:
ReqIF file for the first time.).
Tip
Define what happens if an
object is removed from the Creating a custom date or time field
ReqIF specification since the using one of the options below lets
last Polarion import. you track all Work Items created or
modified by the import.
11. Map each of the attributes defined for the specific ReqIF type to an attribute of the selected Polarion
Work Item type.
12. Once an attribute is selected a appears beside it that lets you define value mappings. You can
define value mappings for all kinds of attributes, but you must map all available values of an
enumeration attribute.
15. When the import process is finished, an overview page opens and contains a table that lists and
provides access to the newly created Polarion Documents.
Tip
When importing a ReqIF, there are two "virtual" ReqIF fields available:
• SPECIFICATION-ID
• SPEC-OBJECT-ID
These allow you to import the information from the IDENTIFIER attributes for the SPECIFICATION
and SPEC-OBJECT fields in ReqIF (respectively).
Examples:
Heading
>Requirement (Item X of type Requirement.)
>Requirement
>Heading
If the item marked X is changed from Requirement to Heading, in order to map the changes to the
document flow, items are repositioned as follows:
Heading
>Requirement
>Heading (Item X is changed from a Requirement to a Heading.)
>Heading
Heading
>Requirement
>Heading (Item X of type Heading.)
>>Heading
If the item marked X is changed from Heading to Requirement, in order to map the changes to the
document flow, items are repositioned to:
Heading
>Requirement
>Requirement (Item X is changed from a Heading to a Requirement.)
>Heading
Auto-mapping
If you need to import a ReqIF file with several documents, it's time-consuming and tedious to manually
map the individual ReqIF types and attributes of all documents on the main page. Auto-mapping simplifies
the mapping of a complex ReqIF file by automatically mapping all ReqIF types and attributes to all its
documents. (You don't need to map them in each document.)
Procedure
1. When the Import Document page appears, while importing a ReqIF document, click Start Auto-
Mapping...
Conflicting attributes (with the same name, but a different type in different specifications) are listed in
a table on this dialog box.
4. Click OK.
Configured attribute mappings are applied to the main mapping page.
Auto-mapper limitations
You can export Polarion Documents to ReqIF files of any supported type. Each exported Document
corresponds to a specification in the exported ReqIF file. As with import, some configuration and mapping
is necessary during the export process.
Export to ReqIF
• Export multiple Documents from the Index page of any Space. Export from here will always be to
a new ReqIF file - you cannot export to update an existing, previously imported ReqIF file this way, but
you can export multiple Documents to a single ReqIF file.
• Export a single Document from the Document Editor. You can only export the open Document, but
you have several options for the ReqIF output and can update a previously imported/exported ReqIF
file.
Procedure
1. Navigate to the Index page of the Space that contains the Polarion Document(s) you want to
export.
3. On the page toolbar, click Export and select Export to ReqIF File.
4. Select a ReqIF format (ReqIF, RIF 1.2, RIF 1.1a ) and enter a filename for the exported file.
Tip
You can reuse an existing mapping template or save the mappings you do now for future exports.
8. (Optional) Click here to download a local copy of the ReqIF file or log to view the export log
(This should happen automatically, so give it a little time before you click here.)
9. Click Finish.
Procedure
1. In Navigation, expand Documents and Pages, browse to the Document you want to export, and
double-click to open it. If there are a number of Documents, you can use the search field at the top of
the Navigation panel.
2. With the Document open in the Document Editor, click , select ReqIF Round-trip then
Export Document.
3. Select an output option and click Start.
• Update existing ReqIF specification: Write changes to a specification in an existing ReqIF file.
If you already imported a ReqIF file (or previously exported a Polarion Document as a ReqIF file),
the target ReqIF file already resides in the repository - not your physical hard drive.
File location in the Repository: Repository/[your_project_name]/.polarion/reqif/documents.
You can access or download a local copy of the file with the Repository Browser.
• Add as new specification to an existing ReqIF file: Create a new specification in an existing ReqIF
file.
Note
DOORS (and some other requirements tools) have a limitation that links can only exist among
items in the same ReqIF file. If you want to import links created in Polarion to such a tool, you
should first export the Document that contains the links target Work Items, then export the
Document that contains the linking items to the generated ReqIF file.
• Create new ReqIF file: Export to a new ReqIF or RIF 1.2 file.
4. Click Start.
5. (Optional) Select additional export options.
Tip
You can reuse an existing mapping template or save the mappings you do now for future exports.
8. (Optional) Click here to download a local copy of the ReqIF file or log to view the export log.
(This should happen automatically, so give it a little time before you click here.)
9. Click Finish.
When exporting Polarion Documents to ReqIF, you must configure export options and map Polarion
artifacts to the desired ReqIF equivalents.
The first section for each ReqIF specification presents several options:
• Export new Work Items and update ReqIF file structure: New Work Items are added to the ReqIF file,
and Work Items are moved within the file. (Change parent or change position.) Usually you select this
only if you "own" the ReqIF file; that is, the file was initially exported by you.
• Update ReqIF metadata (add attributes and enumeration values): Attributes and available values for
enumeration attributes are added according to the mapping configuration. Only select this if you "own"
the ReqIF file.
• DOORS compatibility mode: Triggers additional processing to ensure that the ReqIF file is compatible
with DOORS. Only select this option if you want to import the exported file directly into DOORS without
using an additional tool. (For example, Requisis Rex, Atego Excerpt or Agosense). Currently this setting:
◦ Instructs Polarion to wrap images as OLE objects. (This substantially increases the file size.)
◦ For RIF: Adds a special DOORS-dependent section to the exported file.
◦ For RIF: Controls the naming of default attributes. (Object Heading + Object Text vs. Title +
Description)
If you try to export the file before all required mappings are complete the following message appears:
If you have neglected to configure mappings for an entire section, a appears beside it.
Once all required mappings (in red) are complete you can continue with the export process.
Tip
To save the mappings for use in other exports, select beside the and select Save as template.
Mapping basically is the same as it is for import except that some default attributes are added
automatically when creating a new ReqIF file. For ReqIF, the defaults are added according to the
suggestion of the ReqIF Implementers Forum.
• For RIF, the defaults are Title and Description or Object Heading and Object Text when running
DOORS Compatibility mode.
Note
Only Referenced Work Items from the current Project are exported. (Referenced Work Items within
the Document from other projects are not.)
Tip
An alternative path to reach the mapping and export options page is via a Space's Index page
Export Export to ReqIF File.
(This option exports all selected Polarion Documents into a new ReqIF file, and the configuration page
includes an interface to configure the filename and type.)
When importing or exporting from/to ReqIF, you can save the mappings you define as templates. You can
then reuse the mappings for future import/exports.
Each of the section headers on the mappings page has a drop-down actions menu with actions for
saving the current mapping as a template, or loading a previously saved template. Mapping configuration
templates can be created for both the global and project scopes.
• Document attachments are only exported to ReqIF if they are referenced in a rich text field of one of
the Document's Work Items. So if you import the resulting ReqIF file to another Polarion Document (for
example, in another instance or Project), the original Document attachments are attached to the Work
Items that reference them in their rich text fields.
• When importing RIF or ReqIF files from Polarion to DOORS, the resulting Modules are not editable. To
change this behavior, see the synchronizer.rif.ddcMode and synchronizer.reqif.ddcMode
configuration properties. For more information on the configurations, see the Polarion System
Configuration Properties Reference document.
To locate Documents, you can browse in the Navigation panel, or in the Index page of every Space.
To browse in Navigation, expand Documents and Pages to see the Spaces. Expand any Space's node,
scroll down to locate the Document you want to access, and click on its Navigation node to load the
Document in the Document Editor. If the Space contains Subspaces, you can expand them to see their
contents. If there are too many Documents, Navigation cannot display them all and you will need to
Search to locate the Document(s) you want.
You can also browse for Documents in the Index page of any Space. Expand a Space node in Navigation,
look for Index and click it. The Space's Index page lists all the Documents and Pages in the Space in a table
format. You can sort the table on any of the columns by clicking the desired column headers.
Tip
When hovering over the Smart Title of a Document in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Document link with its Title as the link's label.
If there are too many Documents and Pages for all of them to be listed in Navigation, a message appears
directing you to use Search. In this case, you need to know at least some part of the Document name, or
title (if different from name), or some phrase in its content.
The Navigation panel has a Search text box near the top. As you type, the Navigation panel is filtered
and shows only content in each topic that matches the text you enter. You can enter the first letters of
any word in the Document name, and look for the result in the automatically expanded Documents
and Pages topic. If you are working in a project, then only the project is searched. When you identify
the Document you want to access, click on its node in the Navigation panel to open it in the Document
Editor.
You can expand the search to the entire portal by pressing Enter/Return in the Search box. On the Search
Results page, you can filter the results to show only Documents by clicking the Documents link in the
page header.
After creating a Document, either in the portal or by importing, you can edit it in the Document
Editor. You will see much that is familiar to you from desktop office applications, or if you have used an
online tool like Google Docs. The major difference, conceptually, is that some of your Document content
can be marked as Work Items.
This approach provides the benefits of both office documents, and data-driven process and project
management for the organization. People like business analysts and requirement engineers whose work
typically focuses around documents don't have to change their paradigm or give up much in terms of
functionality and ease of use. People on the technical side get the workflow and data-driven management
capabilities they need. Executives and others responsible for compliance issues get the information they
need. The organization as a whole benefits from improved efficiency, transparency, and communication.
This section focuses on various features and capabilities you will encounter while editing Documents
using the Document Editor. See also Document Editor Toolbar.
Collaboration Notifications
Collaboration Notifications reduce potential Document editing conflicts by showing you who else is
working in a Document you are in. Collaboration status notifications inform you in real-time if someone
else is actively editing or just viewing the Document. It will even notify you if someone saves a change
while you have it opened, so you know to refresh it for the latest version.
Note
Collaboration Notifications are currently disabled by default but can be enabled and configured by an
administrator.
You are the only person in the Document but also opened and edited it in another tab or
browser.
(The icon does not turn orange if you are the only one in the Document and are editing in a
single tab.)
You are the only person in the Document, but you opened it in a different tab/browser and
saved changes there.
The total number of people currently in the Document. (This number dynamically changes as
people enter or leave the Document.)
One or more people are currently editing the Document you have opened. (Orange is triggered
when any change is made.)
One or more people have edited and saved their changes since you opened the Document. (You
might run into merge conflicts when you try and save your changes.)
The service is offline and doesn't know who is currently in the Document.
Note
The number beside the icon always displays the total number of people in the Document with write
permissions no matter what their status is.
(Because they pose no potential conflict risk, people with read-only permissions do not appear in the
list and do not see it.)
After the current user, all other people currently in the Document are listed alphabetically. If they've
specified an avatar, that's the image you'll see beside their name.
Tip
Hover over a long username (truncated by ellipsis) to view their full name and ID in a tooltip.
If the number of people working in the Document exceeds the configured list limit, a more... link
appears at the bottom of the drop-down list.
Click more... to view a complete, searchable list of users currently in the Document.
You can filter this list by username or ID. (Unlike the initial list, the All People in Document dialog box
does not refresh while it's opened.)
If one or more people are editing the Document, the icon turns orange , and an Editing section appears
above the Viewing section in both the drop-down menu and the All People in Document dialog box.
If one or more people save changes in the Document, the icon turns red , and a Latest Changes section
appears above the Editing section in both the drop-down and the All People in Document dialog box.
(Polarion also displays the elapsed time in minutes since the changes were saved.)
Users that make saved changes remain in the Latest Changes section until the most recent version is
refreshed. (Even if they've left the Document. )
So the user count may vary slightly when comparing older versions with the newest, refreshed version.
Note
• If the number of people in the drop-down menu, (listed alphabetically for each section) exceeds the
limit set by your System Administrator, then your name may not appear there.
(You still appear in the All People in Document dialog box.)
• The drop-down menu closes automatically when inactive for five minutes.
If the network connection is lost, Collaboration Notifications are automatically updated when it resumes.
Limitation
Document changes made while a network connection is offline are not reflected by the Collaboration icon
when the connection resumes.
(Even though the icon appears orange , you may be prompted to resolve conflicts when you try and
save.)
Troubleshooting tips
• If you see the following in a Polarion Cluster configuration, the Coordinator machine did not update
correctly during the last Polarion update:
Solution: Follow the configuration guide in the Collaboration Notification section of the Deployment
and Maintenance Guide.
Workaround: Just close the warning. Everything except the Collaboration Notification button will
work correctly.
• In rare cases, a person might appear stuck in the list of people working in a Document after they've left
it.
The Document Editor has its own Find and Find and Replace that even work for text within the
Work Items contained in a Document.
They behave a little differently if On-demand Work Item Loading is set to ON or OFF in the Document
Properties sidebar of the Document you're working with.
Procedure
1. Click Find and Replace in the Actions Menu or use the Ctrl + H keyboard shortcut.
(Clicking Ctrl+ F with On-demand Work Item Loading OFF will launch the Browser's native Find
dialog.)
2. Enter an item to search for in the Find field.
3. (Optional). Select the Match case check box ( ) to only display results with the same
capitalization.
Note
If there is a discrepancy between the number of items found and replaced, it is because non-editable
items, such as referenced Work Items, or TOC entries, cannot be replaced.
Because On-demand Work Item Loading only loads data for that a user has scrolled into view, using your
browser's native Find (Ctrl + F) generally leads to incomplete search results. To ensure that all data in a
Document and its Work Items are searched when On-demand Work Item Loading is turned on, Polarion has
its own Find function. You can still use Ctrl + F, or Find icon in the Actions menu to launch it
Caution
If you use Ctrl + F, click on the Document first. If the focus is on the Navigation panel, sidebar, or
browser window, the browser's internal Find command will be launched instead, and the search results
are likely to be incomplete.
Find:
Procedure
4. (Optional). Select the Match case check box ( ) to only display results with the same
capitalization.
5. Ctrl + H turns an open Find dialog into Find and Replace.
Procedure
1. Click the Find and Replace icon in the Actions Menu or the Ctrl + H keyboard shortcut.
2. Enter the text to replace in the Find field.
3. Polarion automatically begins searching the document, and displays a percentage of its progress.
4. Once complete, it lists the total number of times the item appears and the occurrence number that's
currently highlighted.
5. (Optional). Select the Match case check box ( ) to only display results with the same
capitalization.
6. Cycle through the results by clicking Next> and <Previous.
Click Replace to only replace the currently highlighted item, or Replace All to replace all matching
occurrences.
Because Documents are artifact-aware, that is, they contain Work Items which are tracked and managed
with other tools, the common actions of cutting/copying and pasting of text require some special
considerations and processing behind the scenes. You should keep the following points in mind when
performing any type of cut-copy-paste actions in Documents. In general, cut/copy and paste between
different Documents (also between different projects) will just copy the rich text to the destination, except
when copying Work Items.
Tip
• You can copy and paste a Work Item to another part of the same Document or a different
Document.
• Just looking to move the same Work Item around in a Document? Use the Cut command.
When copying and pasting objects contained within the body of the Document:
• Links are copied/pasted without alteration. If links contain relative paths, the paths might not be valid in
the target Document and you need to recreate them.
• If cut/copied text contains comment markers, these are dropped on paste to the target Document.
With some limitations (see Note below) you can paste an image from your clipboard into the Document
body or into the descriptions of Work Items in the Document. If there is a mixture of images and text in
the clipboard, then only the name of the image file is pasted, and not the image itself. (This is not the case
when you copy and paste a Work Item containing mixed content to another part of the same Document,
or a different Document.)
Note
• If the image and text are cut, then pasted to another part of the same Document, then they'll both
appear.
• Base64 images can be copy and pasted from one Document to another.
• With Microsoft Edge, if you paste Document links and they appear as:
◦ Full/URL/links/to/the/Document
Instead of:
When you past an image, an attachment is automatically created with file name screenshot-
[timestamp].png, where [timestamp] is the date-time when the image was pasted. Supported image
formats are: BMP, JPG, PNG, and GIF.
To paste an image from your clipboard, simply locate the insert point where you want to image to appear
in the Document and use your browser's Paste keyboard shortcut or menu command.
Note
Quality of the pasted image can vary depending on whether you copy the image from your file system, a
web browser, a photo viewer, or image management program, as well as which supported browser you
are using.
While working on a Document you may decide to change the structure and flow of the Work Items.
Spell check
Polarion Documents use your browser's built-in spell checking feature to check spelling in text and
Work Items. Be sure you are familiar with this feature of your web browser and that it is enabled.
A known issue in very large Documents is that browser-based spell checking may negatively impact
performance of the Document Editor or result in memory-usage errors. This has been observed most
often with Firefox. If you encounter such problems with a Document, you may need to disable your
browser's spell check feature while editing it.
Keyboard shortcuts
Shortcut Function
Enter Confirm an action.
Esc Cancel an action.
Alt+Q Focus Work Item query.
Shortcut Function
Alt+E Edit button on all forms.
Ctrl+S Save button in data entry forms.
Ctrl+Shift+S Save button on the Work Items table.
Keyboard shortcuts in the Document Editor are similar to those of applications such as Microsoft Word
and Google Docs. The same shortcuts apply in the Description field and other rich-text type fields in Work
Items. A comprehensive reference dialog, context-sensitive for your operating system, is available via the
Keyboard Shortcuts item on the Help menu of the respective editors.
Document Editor. Work Item detail (Ignore for Shortcuts for the OS you are
first time import.) using.
Shortcuts that focus fields on the form in the Work Item editor
• A - Assignee
• C - Comments
• D - Description
• E - Initial estimate while creating a new item, Remaining estimate otherwise.
• G - Categories
• K,L - Linked Work Items
• N - Time Spent
• P - Time Point
• R - Resolution
• T - Title (edit mode only)
• V - Severity
• W - Status (workflow)
• Y - Priority
Note
It is possible to disable all keyboard shortcuts by setting the property
disableKeyboardShortcuts=true in the system configuration file polarion.properties (follow link
for location).
The following keyboard shortcuts are available in tables in the Work Item Editor (including a Test Steps
table), and the Document Editor:
Shortcut Function
Tab Move cursor to the next cell to the right, or if located in the last cell of a row, to the
first cell of the next row. Content of the cell is selected.
Shortcut Function
If cursor is in the last cell of the last row, insert a new row locating the cursor in the
first cell on the left.
Shift + Tab Move cursor to the previous cell to the left, or if located in the first cell of a row, to
the last cell of the previous row. Content of the cell is selected.
Access point: The Index page of any Space. Click on the toolbar and select Document
in the Create New window.
Tip
Administrators can configure Quick Create so users can create Documents right from the Navigation
Header.
Field Description
Title Human readable title of the Document. Supports non-ASCII characters. Contained
Work Items can be searched using the Document Title visual query element,
entering any part of the value. A value is required.
Tip
Should not be confused with the Document heading style Title.
Name (ID) The unique system identifier of the Document within the project and current
Space. Only ASCII characters may be used. Contained Work Items can be searched
using the Document ID visual query element, entering the exact value only. A
value is required.
Type The Document Type appears only if Document Types are enabled in the project
configuration. Field list contains all the Document Types currently configured in
the current scope. If present, it is a required field.
Space Name of the Space or Subspace in which the new Document will be stored. Field
list contains the names of all Spaces and Subspaces in the current scope. Value
(or Subspace) defaults to the space name from which the dialog box was invoked.
Work Item Type Specifies which type of Work Item the new Document will contain. (More types
can be added after the Document is created.) Field list contains the names of
all Work Item types currently configured in the current scope. Value defaults to
the type specified as the default type in the Work Item Types configuration in
Administration.
Link Role Defines the relationship that hierarchically structured Work Items in the Document
will have to each other. Field list contains the link roles currently configured in the
current scope.
Enable Outline If selected, Work Items in the new Document will automatically be outline
Numbering numbered based on the Work Item level and position in the Document.
Prefix Optional. If specified, the value is prepended to each outline number.
The Document sidebar selector is available when editing a Document. It can display any of several
sidebars showing Comments, Document Outline, and other information about the current
Document. There is also access to tools such as Test Run Planning. Select the desired sidebar via the
sidebar drop-down menu on the Document Editor toolbar.
Commands
Note
Some sidebars are not available when viewing a Document in read-only mode.
Comments sidebar
( Panel settings)
This panel shows the comments that have been inserted into the Document, if any. It also enables adding
of new comments (including threaded replies to existing comments), and removal of existing comments.
Note
Document comments are not the same as the Comments field of a Work Item
Component descriptions
Reply Appears inside a comment balloon when the balloon is selected. When clicked, adds a
new threaded comment one level down.
Delete Removes the selected comment from the Document. Appears inside a comment
comment balloon when the balloon is selected. The comment is not actually deleted in the
repository until the Document is saved.
Sidebar When clicked, displays a drop down menu of settings applicable to the Comments
Settings sidebar. Settings:
• Sort by Document/Time - Controls the sort order of the comments appearing in the
Sidebar.
• Show Resolved Comments - Toggles visibility of comments and comment threads
that have been marked as resolved.
(Resolved comments and threads are hidden to keep them out of the way of
subsequent comments and discussions.)
• Show/hide Unreferenced Comments - Toggles appearance of unreferenced
comments in the Comments page.
Unreferenced comments are comments that have been removed by deleting their
icon in the Document text, but which still exist in the Document repository.
In the sidebar's header. Closes the Comments panel.
Close
This sidebar shows Work Item data fields that can be viewed and in some cases edited right within a
Live Document or Page.
The panel also shows outgoing links from the Work Item currently selected in the Document. Users can
access the linked items, create new links via pasting, and to manage links in a pop-up dialog.
Tip
You can configure the sidebar so that Hyperlinks, Linked Revisions and other Work Item fields are
also visible.
Component Descriptions:
Displays edit controls for the Work Item data fields currently enabled for editing from the
Document.
Links Displays the type icon, ID, and Title of all Work Items that the currently selected Work Item
section has outbound links to. Each item is a hyperlink. If the target item is in the same Document,
the link leads to the properties of the linked Work Item, which display in this panel and
replace the previous information. If the link is to an item external to the Document, the
item opens in a separate browser tab or window.
• Multiple links are split into categories according to link role — has parent, or
implements, for example.
• If you Branch Documents and Overwrite Work Items then links to the source Work
Items also appear in the Links section.
Note
Linked data (OSLC) Work Items also appear in the Links section of the sidebar.
Edit Links Launches the Linked Work Items dialog where you can Add or Remove related Work
Item(s) to the selected Work Item.
If you know the Work Item ID(s) that you'd like to add:
3. Enter the Work Item ID you want to add in the Title and click .
4. Select a Role for the Work Item from the drop-down box.
5. Repeat steps 3 and 4 for all the Work Items that you want to add.
6. Click Confirm when you've finished adding Work Items.
If you don't know the Work Item ID(s) that you'd like to add:
3. Click
The Work Item Picker dialog box appears.
4. Select the scope (Document, Project or Repository) in the drop-down box on the
right.
5. (Optional) Click to filter your query graphically. (For example by type.)
6. Click on a Work Item that you want add.
7. Select a Role for the Work Item from the drop-down box.
8. Click and repeat steps 3 to 7 for all the Work Items that you want to add.
9. Click Confirm when you've finished adding Work Items.
3. Click on the right of the Work Item(s) that you want to remove.
4. Click Confirm.
Documents The Documents section is only visible if the Work Item is referenced in other Documents.
section
This section displays the name of the Document that contains the selected Work Item, and
the names of other Documents that the selected Work Item is referenced in (if any). When
a reference is clicked it opens the document in a new browser tab.
The number of Document references displayed is set to 20 by default but it can be changed
via the following property in the polarion.properties file:
com.siemens.polarion.ui.referencingDocuments.softLimit=20
(The most recently updated documents appear at the top of the list.)
Tip
This requires additional backend configuration. Contact your local partner or SaaS
operations representative for help.
Caution
Due to possible Document optimizations for performance, the displayed result may not
accurately represent the total number of times that the Work Item is referenced.
Hyperlinks
Displays the hyperlinks that are contained within the Hyperlinks section of a Work Item.
Note
The internal and external reference titles above are customizable fields defined in the
hyperlink-role-enum.xml file.
Edit Hyperlinks:
Add a link:
Remove a link:
Note
Removed links will be highlighted in red until the document is saved.
Linked Displays the first 20 revisions (by default) contained within the Linked Revisions
Revisions extension of a Work Item.
(Administrators can configure the default number of Linked Revisions that appear in the
sidebar.)
Click Show more to launch the Work Item in a new browser tab and view all Linked
Revisions .
Note
When a new Linked Revision is added, its Message will be rendered in the sidebar after
the Document is saved.
Note
Removed revisions will be highlighted in red until the document is saved.
Hyperlink and Linked Revision items with long names are truncated, but you can hold
the mouse over them to view their full name in their tooltip.
Sidebar settings
You can specify which data fields appear in the panel, and in what order.
The Select Fields menu option leads to the Select Fields dialog. The dialog displays a list of all standard
fields for the Work Item currently selected in the Document.
Custom fields may be added to the list of Available Fields using the Add Custom Field ID link.
The Add Custom Field ID function is useful when you are configuring a table in the scope of the
current project, but the table you are working on also contains Work Items from other projects where
the configuration of custom fields can be different. Other projects can have custom fields that are not
configured in your current project and so do not appear in the list on the left. Using this Add Custom Field
ID function, you can also add custom fields that are specific to other projects.
Fields in the list on the right appear in the Fields section of the panel. User can remove fields by selecting
fields in the right-hand list and clicking Remove button, or add fields by selecting them in the Available
Fields list and clicking Add button. Fields can be moved up or down in the list by first selecting, then
clicking either the Up or Down button in the dialog. The Reset button returns the Work Item selection to
the default settings.
Tip
The Select Fields dialog box supports multi-select.
The Set as Default button applies the changes and makes them the default for the Document. Other users
will see the selected fields in the Work Item Properties sidebar. The Set as Personal button applies the
changes and makes them the default for the current users. Other users see the Document default fields in
the sidebar.
When a field is selected in the right-hand list, several options appear in the dialog for how to display the
field.
Show in Sidebar Only The field only appears in the Document sidebar.
Show in Document Only The field only appears in the Document.
Show in Document and The field appears in both Document and Document sidebar.
Sidebar
Show At Appears only if option to show field in Document is selected. Controls
whether to show the field at the start or end of Work Items.
Render As Controls whether the Work Item in the Document displays as icon, text, or
both. Appears only for Polarion fields that have an associated icon, and only if
the option to show the field in the Document is selected.
Show Fields at End as If selected, any fields having option set to show them at the end of Work
Table Items will be formatted as a table.
Note
The Work Item Properties sidebar is read-only in History and Baseline views.
• Grayed out fields can only be removed when the report is in Edit mode.
• The fields appear in the Work Item Properties sidebar for all Kanban, Table and Work Items Board
widgets.
• Fields added by a user (when not in Edit mode), are only be visible to them.
• Add fields in Edit mode above if you'd like other users to also view them by default.
• The added fields only appear for the selected Work Item type ( ) and Project.
Usage: View Work Items in the repository that are no longer used in the Document, and access options
for handling them.
This panel displays Work Items removed from the Document but still stored in the repository, and
provides tools for handling them. Open from the Document Editor toolbar, or via the Open in
Document's Recycle Bin button on the toolbar of Work Items currently in the Recycle Bin, when such
items are viewed in the Table view of the Work Items Tracker. Options are:
Tip
For Derived Documents, you can use the Recycle Bin to view Wor k Items that are no longer part of
the Document but cannot Insert, Move or Delete items.
(You can delete them using the Work Item detail form or tracker views like Table or Tree.)
Component Descriptions
• Check box: unlabeled - Selects all Work Items in the Recycle Bin.
• Insert - Inserts selected Work Item(s) into the current Document at the current insertion point, and
re-associates the item(s) with the Document.
• - Permanently deletes selected Work Item(s) from the Recycle Bin and the underlying repository.
• Move - Invokes the Move Work Item(s) dialog which provides the following options:
◦ Move selected Work Item(s) out of Document: Disassociates the selected orphaned item(s) from
the Document, but retains them as project artifacts in the repository where they are managed in the
integrated Tracker and accessed via the Work Items topic.
◦ Move selected Work Item(s) to Document: Associates the selected orphaned item(s) with another
Document, to which they are appended. User must identify the target Document by selecting the
name of the space in which the target Document resides, and then selecting the name of the target
Document.
• - Refreshes the list of Work Items in the Recycle Bin. This can be useful if one user is reading the
Document while another user is editing it, or if one author has removed or merged Work Items in the
Document since the Recycle Bin was displayed in the sidebar.
Content handling
The following tables provide a reference to how various actions affect moving of Work Items to the
Recycle Bin.
Component descriptions
Document information
• Links enabling you to rename the current Document, or change its Type.
Tip
The Change link is disabled if Document Types have not been configured for the project by the
project administrator.
• If you Branch Documents and Filter Work Items or Initialize Work Item fields, this
information appears in the Document Properties sidebar.
Fields
• Document Custom Fields and Document Workflow status, if these have been configured for the
project by the project administrator.
Teamcenter Share
• Displays what Teamcenter Share projects the Document has been uploaded to:
(When you use the buttons below in the Document Properties sidebar the Teamcenter Share project is
prefilled for you.)
◦ Click the Teamcenter Share Project name to view the files it contains in Teamcenter Share. (In a new
browser tab.)
◦ Import Word document updates from Teamcenter Share. (Round-trip from Teamcenter Share.)
(Preselects the Teamcenter Share project and Word document.)
◦ Delete the shared Word document from Teamcenter Share. (It also removes the Teamcenter Share
reference from the sidebar.)
Every time you export, import or delete a document to or from Teamcenter Share, a new revision is
created in the Live Document's History.
Note
This feature requires a special license. See the Teamcenter Share section for details.
Auto-Suspect
Note
This setting is only applied if the Work Items are modified within the Document.
Outline Numbering
• Controls to turn outline numbering on and off, and to specify a prefix for outline numbers.
• Button to toggle on-demand loading of Work Items in the Document. On-demand loading can
significantly improve usability of Documents containing a large number of Work Items. When enabled,
only a few Work Items are initially loaded, enabling the Document to be viewed right away. Other
items are loaded as you scroll. There are currently some limitations.
• Link to the Microsoft Office Word template used for Word Round-trip export.
Edit Links
If the Document is a branched Document, the panel shows the name of the master Document and
provides a link to it.
Usage: View the outline structure of the current Document and jump to content.
• The tree contains nodes for headings and Work Items contained in the Document.
• Clicking any node in the tree structure scrolls the Document to show the selected content. Selecting
content in the Document selects the equivalent node in the outline.
• When content is added to or removed from the Document, the Update button in the page may be used
to refresh the outline.
• The panel provides a filter for the outline, which can help locate content quickly in a large Document.
Simply type filter text in the edit control to automatically and incrementally search the outline structure.
Clear the edit control to remove filtering and restore the full outline.
Attachments sidebar
Usage: Enables you to add new attachments to a Document, to insert an image or attachment preview,
and to view and manage the list of existing attachments.
Component descriptions:
Sidebar header The icon displays a menu with the following items:
Tip
To complete the attachment process after uploading, you must save the
Document.
Insert Preview Inserts a preview of the image or attachment into the Document at the cursor
location.
Update Upload an updated version of the previewed object. (Disabled for read-only
Documents, or for users with read-only permissions.)
Attachments Identifies the section of the sidebar that lists all attachments that are NOT displayed
(section label) in the Document's body. It may contain images, Visio diagrams, and other types of
files. Files listed in this section can be inserted into the Document body by placing
the cursor at the desired spot within the document and clicking Insert Preview
button . Once inserted there, they are removed from this listing in the Attachments
panel and added to the Attachments Visible in Document section.
Attachments Identifies the section of the panel that lists all the attachments currently displayed
Visible in in the Document body. This section may be hidden using the Hide Attachments
Document Visible in Document item in the (sidebar settings) menu. When hidden, it can be
(section label) restored using the Show All item in the same menu.
Tip
Ctrl+V or Command+V can be used to paste images within the Document, but if
they are used for an image in a Work Item within the Document, its thumbnail
will not appear in the Attachments sidebar.
Miscellaneous tips
• No changes to a Document's attachments are permitted if the Document is derived from another
Document. The original Document's attachments must be changed or updated.
• Clicking on an attachment representing an image displayed in the Document body scrolls the
Document to its first appearance.
• Deleting an attachment representing an image displayed in the Document removes the image from all
places where it was displayed in the Document.
Usage: Populate a Test Run with Test Cases from the current Document.
This panel enables you to select Test Cases to be tested when a Test Run is performed by testers.
Component descriptions:
ID {name} Displays the ID of the Test Run for which Test Cases are being selected or removed.
(Read only)
Template Displays the name of the template on which the Test Run shown in ID is based. (Read
{name} only)
Waiting Shows a count of the Test Cases currently populating the Test Run.
Executed Shows a count of the Test Cases current populating the Test Run which have not
currently been tested.
Add Adds one or more Test Cases, selected in the Document body, to the queue of waiting
Test Cases for the Test Run. Enabled when the Test Case(s) not already in the Waiting
queue is/are selected in the Document.
Remove Removes one or more selected Test Cases, selected in the Document body, from the
queue of waiting Test Cases for the Test Run. Enabled when the Test Case(s) already in
the Waiting queue is/are selected in the Document.
Estimated Displays the total estimated time needed to test all Test Cases currently populating
Execution Time the Test Run. Each Test Case has a field for storing the estimated time needed to test
it. The value is populated by adding the Initial Estimate values from every Test Case
Work Item type associated with the Test Run.
Save Test Run Saves the current Test Case selection to the Test Run.
The Configure Work Item Presentation dialog box is where you can specify the type(s) of Work Items
a Document can contain, and how elements marked as Work Items appear. (What data fields appear
along with the text.) For example, you might display the ID and Severity in paragraphs marked as
Requirements, or the ID and Status in paragraphs marked as Test Cases. You can even configure it
so elements within a Document (like a paragraph) can be marked as a Work Item.
Click Configure on the Document Editor toolbar to launch the Configure Work Item
Presentation dialog box.
Content (paragraphs, headings etc.) in Documents can be marked as Work Items. You can automate
this with Work Item Rules when a Document is created from a Word import, or manually by a user.
• Type: The Type of Work Items you can use in the Document. Displays the Types configured for the
project in the workitem_type_enum.xml enumeration file. (See: Configuring Enumerations.)
• Label: By default, it's the name of the Work Item Type specified in Type. (You can change it, but there is
usually no need.) This value appears in the drop-down menu of the Document Editor toolbar.
• Content: Specifies what content is included when a new Work Item is inserted, or Document text is
marked manually (or automatically via import rules) as a Work Item.
Tip
◦ If you select Description, all selected content is placed in the Work Item's Description and no
value is set for its Title. When viewed in the integrated tracker, the Title is created from the first 80
characters of the Description. No separate title appears in the Document.
◦ If you select Title and Description, all selected content is placed in the Description, and a line for
Title is created. If you do not enter Title text, Polarion copies text from the Description until you
set something in the Title field. Once you do, Title is maintained as a separate data field.
If the setting in Content includes Title and/or Description, the ENTER keyboard shortcut has
different behavior in these fields.
◦ If you have a Work Item configured to display the Description of a Work Item, then any marked
text appears in the Description when you mark it as a future Work Item.
◦ When the Description has content, but the Title does not, Polarion automatically generates Title
content from the Description content when you save.
◦ If Title is configured in the Type presentation but Description is not, the text you highlight is
placed in the Title field, all formatting and attachments are removed, and the Description remains
empty when you save.
(If a Description is configured as Required before a save, configure the Work Item presentation
so that it includes a Description and only change to a Title (only) configuration after you are done
creating the new Work Items.)
• No Page Break: Polarion attempts, where possible, not to have page breaks within Work Items when
Exporting the Document to PDF, or Round-trip for Microsoft Word.
• Hidden: If selected, the Work Item Type is not displayed in the drop-down menu of the Document
Editor toolbar. The presentation will be applied to existing Work Items of the type specified in Type (if
any), but users will not be able to apply it manually to new or existing Document content.
• Actions:
Select Fields
Here you can specify the Work Item fields (including custom fields) that you want visible in the Document,
where they should appear, and their layout.
• Show in Sidebar only: Selected Fields only appear in the Work Item Properties sidebar.
• Show in Document only: Selected Fields only appear in the Document.
• Show in Sidebar and Document: Selected Fields appear in the Document and Work Item Properties
sidebar.
(Fields set so they are shown in a Document are also Exported to PDF, or Round-trip for Microsoft
Word.)
• Show Fields at End as Table: Select to have Fields appear at the end of the Work Item instead of the
start (default).
(For example, you might have the outlineNumber value appear at the start, and the Severity field
at the end of paragraphs that are marked as Work Items.)
You can display multiple field values at both the beginning and end of marked elements. For example,
you might show OutlineNumber and ID at the start, and Severity and TimePoint at the end of
paragraphs marked as Work Items.
Tip
You can also launch the Select Fields dialog with the (Sidebar Settings) icon in the Work Item
Properties sidebar. (Enabled when a Work Item is selected in a Document). When invoked from there,
the field configuration can be saved as a user-specific personal configuration only for the current user, or
as the default for the Document.
The Document Editor toolbar contains most formatting options you are familiar with in desktop word
processors.
The toolbar is also available in the Test Execution View. Toolbar actions are listed in this topic as they
appear left to right on the toolbar
Action Description
Save Saves changes to the Document. Disabled when there are no unsaved
changes.
Redo Reapplies changes undone by Undo until the limit of undone actions is
reached.
Applies paragraph or heading styles to the current paragraph.
Paragraph Type
Bold Formats selected text, or text forward from insertion point, in a bold font.
Italic Formats selected text, or text forward from the insertion point, in an Italic
font.
Contains the following formatting options:
- Underline,
Formatting - Strike-through,
- Subscript,
- Superscript,
- Text Color,
Action Description
Color Picker
Font
Enables font size selection.
Font Size
Convert to Text
Mark/Unmark Work
Item
Clicking on the item's Work Item icon marks or unmarks selected text as a
Work Item. Drop-down menu enables marking selected text as one of the
listed Work Item types, if multiple types are configured in the Document
Work Item presentation. The Configure item access the Configure Work Item
Action Description
Presentation dialog where type(s) and other properties of Document Work
Items are specified.
Tip
This dialog box supports multi-select.
Enabled if current selection does not contain a Heading, Wiki content, TOC,
or Work Item. Also means that selection does not contain two or more Work
Items, or combination of more top level elements.
Enabled if current selection contains only one Work Item and nothing else.
Ordered List Formats the current paragraph as a Numbered list (ordered list) item.
Unordered List Formats the current paragraph as an unordered (bullet) list item.
• Only top-level list items are affected. Numbering of further levels always
Renumber
begins with "1".
• Continue Numbering is available for plain text, contained Work Items, and
referenced Work Items.
• Continue Numbering is available only in the Document Editor. Work Items
containing continued lists will show lists continuing with "1" in other Views
(Table, for example), but the continuation is preserved in the Document.
• List continuation is preserved in Round-trip export for Word. Changes from
Word should be re-imported correctly unless a list is interwoven with a
different list type - bullet list, for example.
• Continuation is preserved in copy/paste operations within the same
Document.
Outdent Outdents the current paragraph one level. Disabled if the current paragraph is
already as far left as it can go.
Indent Indents the current paragraph one level until the indent maximum is reached.
Action Description
Sets the alignment for the current paragraph. The action will be denied if the
Alignment
cursor is located in a heading or Work Item text. In a Work Item description,
only the alignment of images and tables is supported. (An entire table or just
text in a single cell). An image is aligned only when selected.
Insert Image or Launches the Insert Image or Attachment Preview dialog with options
Attachment Preview to upload a local image, select an image attachment, or insert an image
currently on your clipboard. The image is inserted at the current cursor
position.
Enabled if current selection does not contain a Heading, Wiki content, TOC, or
Work Item title.
Insert several types of content into the Document. See Insert Menu.
Insert Menu
Inserts a table on the current line if it is empty, or on a new line if not. It is also
Table
used to modify an existing table (Add, Remove, Merge or Unmerge previously
merged cells.)
Show Sidebar Displays a menu of Document Sidebar panels and opens a selected panel.
Action Description
Displays a menu of Work Item Views and opens a selected View in the Work
Item Tracker. The opened View contains all Work Items in the Document.
View
Document Options
Insert Menu
Action Description
Comment Inserts a comment marker at the current cursor position, opens the
Comment sidebar, and inserts a new comment that's ready for editing.
Image or Attachment Available on the toolbars found on Pages, LiveDocs and rich text Work
Preview Item fields. It launches the Insert Image or Attachment Preview dialog.
The dialog initially displays previews of images and attachments that are
already attached.
Action Description
Link or Cross-reference Launches the Insert Link dialog where a Live Link URL or a Cross-
reference can be specified. A hyperlink to the specified URL is inserted
at the cursor position. If the Live Link or Cross-reference refers to an
item that contains outline numbers, you'll also have the option to
include them in the link's text. The cross reference's outline numbers
and title update automatically whenever its source's numbers or title
change. Enabled if the current selection does not contain a Heading,
Wiki content, TOC, or Work Item title.
Diagram Launches the Diagram Editor and inserts a new diagram at the insertion
point when diagram is saved in the Editor.
Table of Contents Inserts a table of contents on the current line (if empty) or above it if
not.
Wiki Content Launches the Insert or Modify Wiki Content dialog in for selecting
Wiki syntax and mark-up that inserts Wiki content (macros, for
example) into the Document.
Page Break Inserts a page break on a new line. Page breaks are applied when the
Document is exported.
Operations Menu
Action Description
Filter Displays the filter bar where you can enter a query that filters the Work
Items shown in the Document. For example, the query status:open
would filter the Document to show only Work Items with an Open status.
Find and Replace Displays the Find and Replace dialog, enabling you to find and
optionally replace text in the current Document. (Including text
contained in Work Items.)
Action Description
Print Launches the Print dialog that displays a print preview of the Document
and provides print options.
Document Baselines let you mark and label specific historical changes
Create Baseline
to a Live Document as baselines.
Export to PDF Launches the Export to PDF dialog with several export options and
exports the Document content to a PDF file.
Rename Launches the Move or Rename dialog with options to Rename the
document or Move it to another Space.
Reuse Launches the Reuse Document dialog with options to reuse the current
Document.
Branch Launches the Branch Document dialog for branching the current
Document to create a variant.
Compare With Enables user to compare the current state of a Document with some
other Document, or the last saved version of the current Document.
Caution
Changes saved by another user after you've loaded a Document
will not be detected.
Word Round-trip Via its sub-menu, let you Export the current document to Microsoft
Word for review, comment, or editing by an external user, and Import
Changes in a previously exported Word round-trip document back into
Polarion.
Action Description
For more information, see Sharing Documents Using Word Round-trip.
ReqIF Round-trip Lets you Export a document in the ReqIF (Requirements Interchange)
format or Import Changes made to a ReqIF document outside
Polarion, back into the portal.
When Document text is marked as a Work Item, an icon representing the Work Item type appears in the
left margin. Clicking the icon displays a menu with the following actions.
Open Item - Opens the Document-defined Work Item in the Table view.
Copy ID - Copies the ID of the Work Item to your computer's clipboard.
Copy Item- Copies the selected Work Item.
(You can paste it somewhere else in the same Document or an entirely new
Document.)
Copy Link - Copies the complete URL of the Work Item to your computer's
clipboard.
Copy Cross-reference - Creates a Cross-reference link that you can paste
somewhere within the same Document that will bring users right back to the
item when clicked.
Cut - Copies the complete URL of the Work Item to your computer's clipboard.
Unmark - Unmarks the current Work Item, reverting the content to regular
Document text and sending the Work Item to the Document Recycle Bin
(viewable in the Document Sidebar).
Delete - Deletes the current Work Item.
Insert - Inserts a paragraph above or below the current caret position via one
of the sub-menu items.
A Referenced Work Item links to a Work Item that resides in another Document. Its content can only be
edited in the original Work Item, but if you use the Overwrite action, you can create a copy of the Work
Item's content with a new ID and store/edit it within the current Document.
(An is branched from link role to the original item is created automatically.)
Open Item - Opens the Document-defined Work Item in the Table view of the
tracker.
Copy ID - Copies the ID of the Work Item to your computer's clipboard.
Copy Link - Copies the complete URL of the Work Item to your computer's
clipboard.
Cut - Places the item in the Document Recycle Bin. (Viewable in the Document
Sidebar.) You still have the option to Undo this operation and reinsert the item
back into the LiveDoc.
Unmark - Unmarks the current Work Item, reverts the content to regular
Document text and sends the Work Item to the Document Recycle Bin. (Viewable
in the Document Sidebar.)
Remove - Removes the Referenced Work Item. (No option to undo once the
LiveDoc is saved.)
Freeze - Freeze the Referenced Work Item at a specific revision.
Overwrite - Creates a copy of the Work Item's content with a new ID, stores the
item within the current LiveDoc and creates an is branched from link role to the
original item.
Properties - Launches the Work Item Properties sidebar.
Insert - Inserts a paragraph above or below the current caret position via one of the
sub-menu items.
When outline numbering is enabled in Documents, outline numbers appear for Document headings
and Work Item titles in the Document Editor. This topic describes the display of outline numbers in
the Table and Tree Table views of Documents, including Work Items referenced from a different
Document.
• If an outline number is assigned to a Document-based Work Item, then the Work Item Table and
Tree views show the outline number from the Master Document (the Document that actually contains
the original item).
• When a Document is selected in Navigation and viewed in the Table or Tree views, and a Work Item is
selected the table or tree, the outline number you see in the Outline Number column of the table/tree
is the outline number from the Document selected in Navigation. The value in the Outline Number
field in the selected Work Item's detail form may be different from the value in the table column if the
item is referenced from another Document. In that case, the value in the field is the outline number
of the item in the Master Document - the Document that actually contains the Work Item and from
which it is referenced to other Documents.
• If a Work Item has no outline number assigned, then the Outline Number column in the table section
of the page shows only icon representing the Work Item type.
Legend
The order of precedence used by the PDF exporter for watermark images in PDF output is as follows:
Project repository is checked first, followed by global repository. If no suitable image is found in any
scope, no watermark is included in the PDF output, and an error is written to the log files. For additional
information, see Multiple Watermark Images.
Your ability to access and use Document features depends on the permissions assigned to your user
account, which may be tied to the user role(s) assigned to you by the system or project administrator. The
license you are currently using may also affect your ability to use some Document related features. This
section provides some specifics that may help if you find you cannot access or use some feature or perform
some operation.
Word Import:
• The Import action is only available if you have permission to create Documents and Work Items and
you are using either an ALM or a Requirements license.
• Even if you have the user permissions above, you can only save import rules if you
have write permissions for the relevant repository location, specifically, polarion/tracker/
import_configurations/word/.
Word Round-trip:
• You can invoke Word Round-trip > Export when you have read-only permission for a Document
provided you are using an ALM or a Requirements license.
• To import changes in a Word document modified after round-trip export, you need to be using an ALM
or a Requirements license, you need to have write permission for the Subversion repository, and also
the Polarion permission to modify Documents.
Polarion provides project managers the ability to exert control over who can do what with a Document.
This is accomplished by configuring Document permissions in global and/or project administration. This
section describes the Document permissions that can be assigned and what they allow users who have
the respective permissions.
READ Allows user to read Document content and view Document information in the
Document Properties sidebar.
CREATE NEW Allows user to create new Documents, provided that they are also granted MANAGE,
MODIFY FIELDS, and MODIFY CONTENT permissions.
MODIFY FIELDS Allows user to modify Document fields (Status, for example) and custom fields shown
in the Document Properties sidebar.
Granting the MANAGE and/or MODIFY CONTENT permissions for Documents does not
grant the permission to MODIFY FIELDS.
MODIFY • Add/remove/move Work Items, including Headings and Referenced Work Items,
CONTENT to/from/within the Document structure using the Document Editor.
• Move Work Items, including Headings and Referenced Work Items, to/from the
Document Structure via the Move Work Item dialog.
• Fields that appear in the Content column of the Configure Work Item Presentation
dialog (Title, Description, and Test Steps, for example).
• Add, modify, or remove Document attachments.
• Add, modify, or remove attachments to Work Items of all types contained in the
Document (including Headings), provided user also has permission to modify Work
Items in the project.
• Add, edit, or delete plain text in the Document. (Text that's not contained in Work
Items.)
• Users who are denied this permission, but who are granted the COMMENT and/or
RESOLVE COMMENT permission, can insert comments into the Document and/or
resolve comments in the Document (in text and Work Items).
Warning
If MODIFY CONTENT is granted, do not also explicitly grant COMMENT or
RESOLVE COMMENT permissions.
The granted user will automatically be granted them.
• This permission does not apply to referenced Work Items in the Document.
• Granting this of permission does not grant permission to MODIFY FIELDS.
• Granting of the MANAGE permission for Documents does not grant permission to
MODIFY CONTENT.
MANAGE Allows user to:
• Configure default Work Item type(s) and Work Item presentation for the
Document.
• Change the Document type (if the Document types feature is enabled).
• Move or Rename a Document.
• Upload a round-trip template.
• Configure Document outline numbering.
The following table lists the permissions required for different Document-related actions, and the
capabilities/features available when a user has the listed permissions.
• READ Document,
• READ Work Item.
Note
• Documents appear in the Documents and Pages topic in Navigation.
• READ Document
• READ Work Item
Note
• Documents are read-only.
• Round-trip and PDF exports will work.
• READ Document
• MODIFY Document
• CREATE Document
• READ Work Item
• MODIFY Work Item
• CREATE Work Item
Note
• Option to create new Document appears in Space Index pages and Space Overview.
• Import for Microsoft Word is available.
• READ Document
• MODIFY Document
• CREATE Work Item
• READ Work Item
• MODIFY Work Item
Note
• Modify Document body text.
• Modify Work Item Description and Fields.
• Mark/Paste or Unmark/Cut/Recycle Bin Work Items.
• Mark/paste OR unmark/cut/delete Headings.
To control the deletion of headings via the DELETE permission, then have your administrator set the
headingsObeyDeletePermission system configuration property to true. (Otherwise it's enough
to have the MODIFY CONTENT permission.)
• Round-trip Import is available.
Required permissions are the same as for Modify a Document, plus DELETE Document
Note
Note
• Changes are imported if there are no errors or invalid data.
This section the level of support in the export operation of Word Round-trip for text formatted with Wiki
mark-up and inserted into a Document, and for Wiki macros which may be inserted into a Documents.
Items with full and partial support are listed. You can assume that any mark-up and macro not listed
here is not supported when a Document is exported to Microsoft Office Word using the Word Round-trip
feature. It may still be possible to export Documents containing unsupported mark-up and/or macros, but
formatting and content in the exported document may be sub-optimal or missing.
• Headings: converted to Word as native Word headings; style of Wiki/Document headings is not
preserved
• Generic formatting, including: bold, underlined, italic, strike-through, monospace, subscript and
superscript
• URL links such as [https://www.polarion.com], [Polarion >https://www.polarion.com]
• Lists (unordered, ordered, hybrid multi-level)
• Escaped text, explicit line break ( \'), horizontal rule '---')
• {code} macro: text is converted into Word in monospace font (Courier New)
• {quote} macro
• {workitems} macro. Some styles may not be converted, but the macro is generally supported.
• Document macros:
1. {document}: link is converted to Word (with icon)
2. {document-workitems}: Note that tables are not converted completely to Word.
3. {document-property}
• Project macros:
◦ {project-property:active}
◦ {project-property:description}
◦ {project-property:finish}
◦ {project-property:lead}
◦ {project-property:location}
◦ {project-property:name}
◦ {project-property:[PROJECT NAME]|users}
Where [PROJECT NAME] is the name of a project. Example: {project-property:drivepilot|
users}
◦ {project-property:start}
◦ {project-property:users}
• {pages} macro
• {timepoint} macro
• {show:pdf} macro: the content is shown only when document is exported to Word
The following elements and macros are partially supported during export to Word. For example, content
may export but formatting does not.
When importing a Microsoft Word document in which content that should be recognized as Work Items
is contained in a table, you need to specify an import Rule that recognizes Work Items in tables. You may
also want the Rule to run some action(s) on these table-contained Work Items when the document is
imported to Polarion. This is done using regular expressions with the text matching regex rule type option.
This topic provides some examples.
Risk High
Steps Hello World
Department 34
These regular expressions can be used to parse the values from the above table:
Note
The selected fields must actually exist within the target document in order to work.
You can also extract fields from tables that match enumerations with the following regular expression:
Severity[\s&&[^\t]]*\tLow\t\n
See the topic Configuring Automatic Work Item Recognition for information about recognition of other
content elements.
If users have created and saved Document import configurations (that is, rules for recognizing Work Items
in imported Word documents), at some point in may become desirable to delete some configurations
that are no longer necessary or used. There are several points to remember about deleting import
configurations:
• There is no graphical user interface for deleting import configurations. They must be deleted from the
repository.
• The repository folder storing import configurations is:
/.polarion/tracker/import_configurations/word or [PROJECT]/.polarion/tracker/
import_configurations/word
You can use PolarionRepository Browser or an external Subversion client to browse to the import
configuration folders.
• If an import configuration for the repository scope has been overridden in a project, the configuration
cannot be deleted at the repository level.
• A user must have change permissions for the repository folder(s) containing import configurations in
order to delete any import configuration.
Polarion always attempts to preserve the formatting of imported Microsoft Word and Excel documents,
and of exported Polarion Documents. In general:
• Font size and family is imported from Word and Excel documents except the Normal style.
• Polarion imports only known fonts defined by the system configuration that are replaced on import by
the font substitution settings of the Polarion system.
• Text color and text and table cell background color is imported from Word and Excel documents. Text
background color set text strings in body text or table cells is not imported. In cells, only the cell
background color is imported.
• Font size, font family and colors are exported during Word and Excel round-trip.
• Font size, font family and colors are exported by PDF Export
The following IDs can be set in a project-scope Word Round-trip export template, and are visible in the
header or footer of exported round-trip files:
ID Description
created Date/time when the Document was originally created
createdBy User who originally created the source Document
date Current date
documentName System ID of the source Document
documentTitle Title of the source Document
generated Date the round-trip document was created
generatedBy Name of the user who exported (generated) the round-trip document
productName Name of the Polarion product used to create the round-trip document
productVersion Version of Polarion used to create the round-trip document
projectId ID of the project containing the source Document in Polarion
projectName Name of the project containing the source Document
revision Revision number of the source Document
space System ID of the space containing the source Document
spaceTitle Title of the space containing the source Document
updated Date/time when the source Document was last updated
updatedBy Name of user who last updated the source Document
A Round-trip Export template is a Word .docx document that is used by Polarion as a basis for creating a
Word round-trip document from a Polarion Document. Templates can define, for example, header and
footer, table of contents, heading styles, etc. This section specifies where such templates are stored in the
repository in case you wish to customize them.
• The location of the global default template, used for export of Documents created in the portal
is: /.polarion/tracker/templates/roundtrip.docx. This template is accessible via the
Administration topic Work Items Round-trip Template in the Repository scope.
• You may create and upload a project-specific copy of the global default template to be
used for all round-trip exports from a specific project. Project-specific templates are stored as:
[PROJECT]/.polarion/tracker/templates/roundtrip.docx. You can create and access a
project-scope round-trip template via the Work Items Round-trip Template in the project scope.
• If a Document is created by importing a Word Document, a document-specific round-trip
export template file is created and stored in the Document folder:[DOCUMENT_NAME]/templates/
roundtrip.docx. This template is accessible in the Document Properties panel of the Document
Sidebar. You can either upload a customized template (one that was downloaded before and modified),
or it can be one you have created as a template out of any Polarion-created Document (these options are
presented in the upload dialog).
For more information on using Word Round-trip and round-trip export templates, see: Share Documents
Using Word Round-trip and Use Round-trip Export Templates.
If you have default round-trip templates in some project(s) that you no longer need, these can be
deleted using the Repository Browser. Navigate to the project location as described above and delete
the roundtrip.docx file.
Warning
Do not delete the global default round-trip template: /.polarion/tracker/templates/
roundtrip.docx
You can delete a Document-specific round-trip template using the Remove (use default) link in the
Document Properties panel of the Document Sidebar in the Document Editor.
The following items apply when Document Work Items are exported to Excel using Allow Document
structure changes in Excel, and an external user modifies the Document structure in the exported Excel
workbook.
• When a heading is removed in the exported workbook, lower level headings below the deleted heading
are not promoted, but rather retain the same level they had upon export from Polarion. The user should
change promote lower-level headings occurring after deleting a higher-level heading.
• An heading added in the exported workbook is always 1 level higher in the structure as compared to the
previous heading.
• If it is desired to preserve non-sequential headings occurring in a Document - "Heading 1" followed
by "Heading 3", for example - then modifying headings in an exported Excel workbook is not
recommended. On import, Polarion will fix the structure, promoting the "Heading 3" in the example
to "Heading 2".
• Related to the previous, any invalid hierarchy created in the exported workbook (missing heading level
between Work Items) will be silently fixed when the modified workbook is re-imported to Polarion and
the online source Document will reflect a valid hierarchy.
• When adding a row in the exported Workbook, the user must write some content before attempting to
indent it.
• The following points apply when conflicts are encountered upon re-import of a modified exported Excel
workbook:
◦ If a Work Item is unmarked or deleted on server after being included in an export to Excel, and the
item is not modified in the exported workbook, the importer ignores the item in the worksheet and
does not re-import it. ("Modified" means modified value, not level or position.)
◦ If a Work Item is unmarked on the server after being exported to Excel, and it is modified in the
exported workbook, then item is updated during re-import to Polarion.
◦ If a Work Item is deleted on server after export to Excel, and then modified in exported workbook,
the importer treats it as a conflict. The import fails, or changes to the deleted items are ignored,
depending on the import option settings selected by the user importing the workbook.
If you and another user edit the same Document at the same time, your changes might conflict with
changes made by the other user. This topic provides some examples of scenarios in which concurrent
changes by different users are merged silently, and other scenarios that will trigger a Concurrent Changes
warning dialog box.
Tip
See Resolve conflicts for details on how Polarion handles conflicting concurrent changes to a
Document, how to prevent conflicts, and how to resolve them.
Automatic merging
The following concurrent Document editing actions are automatically merged without any message to
users:
The following list describes some example scenarios in which changes are safely and silently
merged:
• User 1 modifies an existing paragraph in the Document body, or in the description of a Work Item.
Changes are not yet saved.
User 2 adds a new paragraph below the paragraph User 1 is editing, and saves the change.
User 1 saves pending changes.
• User 1 indents a Work Item to make it a child of the previous item. Changes are not yet saved.
User 2 modifies the description text of the same Work Item, which does not appear indented, and saves
the change.
User 1 saves the pending change.
• User 2 creates a new Heading at the end of the Document, then cuts an existing Work Item, and
pastes it below the new Heading. Changes are not saved.
User 1 modifies the description of the same Work Item, which still appears in the original position in the
Document, and saves the change.
User 2 saves the pending change.
The following concurrent Document editing actions are automatically merged with relative safety after
a warning message to users:
• Change to different properties of the same Work Item. Warning appears to the latest user to invoke
Save. Merge is performed if user confirms Save in the warning dialog box.
• Merging of other changes if the same property(ies) of a Work Item are changed. Changes of latest user
invoking Save overwrite the conflicting change in Work Item property and merges other changes if user
confirms Save in the warning dialog box.
• One user is reordering items in the Document while another is reordering, adding or removing items at
a different place in the Document.
Note
All Document revisions are automatically saved in the History. If some changes are overwritten
by mistake, it is always possible to copy the "lost" content in the historical revision where it was present,
and paste it to the current revision of the Document.
When the current user saves changes, if the merge algorithm detects that the changes either might be
lost, or no longer make structural sense because of changes made by another user working concurrently
with the same Document, it stops the merge process without saving the current user's changes, and
a warning dialog box is shown to the current user. The dialog box summarizes the issues, provides some
explanatory Help text, and provides links that open separate browser tabs in which the current user can
review his or her potentially conflicting changes, and the changes of other users. The user can then make
an informed decision about saving the pending changes. The current user can either make corrections
that resolve the conflict(s), or proceed with an unsafe merge which may overwrite another user's recent
changes, or elect not to save their own changes.
The following list describes some example scenarios that lead to a warning about conflicting concurrent
changes:
• User 1 and User 2 modify text of the same paragraph, which may or may not be part of a Work Item's
description. The last user to save their changes receives a Concurrent Changes warning.
• User 1 and User 2 modify the same table, which may or may not be part of a Work Item's description.
The changes may be made in the same, or in different parts of the table. Changes may include adding
or removing rows or columns. The last user to save their changes receives a Concurrent Changes
warning.
• User 1 and User 2 edit the same diagram, which may or may not be part of a Work Item description. The
second user who attempts to edit receives a message warning that another user is currently editing the
diagram and that changes will not be merged.
User 1 modifies a diagram, updates it in the Document, and saves the Document. User 2 then modifies
the same diagram and saves the Document. User 2 receives a Concurrent Changes warning.
• User 1 adds an image, or a diagram, or a table to a Work Item while User 2 is updating the text of the
description. The last user to save their changes receives a Concurrent Changes warning.
• User 1 indents a Work Item to make it a child of the previous item, but has not yet saved the change.
Meantime, User 2 modifies the description text of the same item, without indenting it, and saves the
change.
Now User 1 saves. So far, so good.
Now User 2 indents the same Work Item and saves. User 2 receives a Concurrent Changes warning.
• 1. User 1 creates a new Heading, then cuts an existing Work Item, pastes it under the new Heading,
and adds a new paragraph to the description.
2. Meanwhile, User 2 modifies the description text of the same Work Item, which still appears in its
original position in the Document, and saves the change.
3. Now User 1 saves pending changes. User 1 receives a Concurrent Changes warning.
Conversely, if User 1 saves changes before User 2 updates the description text, then User 2 would
receive the Concurrent Changes warning when saving.
Any time during the authoring process of a Document, you can mark some parts of its content as Work
Items. Marking content creates a Work Item artifact in the underlying repository, enabling the team to
take advantage of all the traceability, workflow, reporting, and other management features. Document
authors can continue to work with content in a straightforward document-like editor.
Tip
While there is no hard limit to the number of Work Items you can have in a Document, the
recommended best practice is that you keep it under 5000.
By default, Documents can contain Work Items of the type named Heading, and one other type specified
by the user who creates the Document. Work Items created in Documents are tracked through their
lifecycle and managed with workflow. They are also accessible in the Work Items topic for those who
prefer a more tool-based interface.
After a Document is created, one or more additional user-defined Work Items types can be configured,
enabling users to mark Document content as a Work Item of any of the configured types. For example,
a team might choose to have requirements and test cases in the same Document. See Configure
Document Work Item types for specifics.
Note
• If the Project doesn't have a Heading Work Item type defined, you'll be able to use them in the
Document Editor, but won't be able to customize them.
• To customize Headings (for example, define custom fields for them), you must define them as a
Work Item type.
Once you do, you'll unlock the ability to configure them as you would any other Work Item type.
To make changes in a Document, you must have permissions to modify Documents, to create new Work
Items, and to modify Work Item fields. If you are denied permission to modify any fields, some restrictions
on creating new Work Items are imposed. For details, see Work Item Field Permission Restrictions: New
Work Items.
There are some restrictions when editing a Work Item directly in a Document if it has read-only
permissions applied to some of its fields.
(For example, you can't edit a Work Item's Description, even if it's not one of the read-only fields.)
Tip
• Edit Document Work Items in the Work Item Editor to bypass restrictions imposed by the Document
Editor.
(Read-only restrictions imposed by your administrator will remain.)
• Enter a Title and Description for your Work Item so that it's readable in all Polarion views.
(See How Work Item Titles are created and updated to learn how Polarion auto-creates and updates
Titles if they are not explicitly defined.)
• You can change the Title and Description by opening the Work Item in Table or Tree view.
1. While in the Document Editor, select the Work Item that you want to edit.
2. Click on the top right to open the Work Item in Tree view. ( Table view will also work.)
The Work Item you selected is highlighted in the list and appears in the Work Item Editor below it.
3. Click Edit.
4. Make your edits to the Work Item, click Save and OK to confirm.
By default, Documents contain only one Work Item type — Requirement, for example. You specify
the type when creating a new Document. In many cases, one Work Item type per Document is enough
and you need do nothing more after you create a Document. However, Documents can contain more
than one Work Item type. For example, you might want a Document to contain Work Items of a type
named Requirement and Work Items of a type named Test Case. If Requirement was the type
specified when the Document was created, then you need to add the second type, Test Case, to the
Document configuration before you can mark any content as a Test Case.
Procedure
1. In the Document Editor toolbar, click the Work Item Type drop-down list.
See also Configure Work Item Presentation Dialog, Display Data Field Values and Change Work Item
Type.
You can insert Work Items contained in some other Document into a Document you are currently
working on. These referenced Work Items may be contained in another Document in the same project,
or in a different project. Once inserted in the current Document, they can be read but not modified. It is
possible that referenced Work Items might be of a type not currently specified in the current Document's
configuration. The type might not even exist in the current project's configuration. Polarion handles these
scenarios in different ways, which you should be aware of.
• If a Referenced Work Item is from same project as the Document you are working on, but that
Document is not configured for the referenced type, then Polarionautomatically adds the type of the
For example, suppose there is a requirements project that has a requirements specification Document that
is configured to contain Work Items of a type named Requirement. Suppose also another project that
has a test specification Document configured to contain Work Items of a type named Test Case. Now
you want to insert some Work Items of the Test Case type, by reference from the test specification
Document, into the requirements specification Document. However, the requirements specification
Document is configured to contain only one Work Item type — Requirement. Furthermore, the
Test Case type is not even defined the requirements project configuration. When a referenced Work Item
is inserted via the Mark/unmark text menu, Polarion automatically updates the Document configuration
of the requirements specification with the Referenced Work Item type — Test Case in this instance —
allowing items of that type to appear in the Document. The properties of the added type (Label, Content,
Fields, etc.) can be edited in the Document Presentation dialog box.
Procedure
1. Select all the text you want included in the Work Item. If you select multiple paragraphs, they will all
be included in the same Work Item.
Tip
See the How Work Item Titles are created and updated section below to learn how Polarion
auto-creates and updates Titles if they are not explicitly defined.
2. On the Document toolbar, click the icon representing the type of Work Item initially configured for
the Document.
3. In the menu that now appears, select the desired Work Item type. If only one type is configured, only
that type appears. The selected text is marked as a Work Item, and the icon for the specified type
appears just outside the left-hand border of the editor. The artifact in the underlying repository is not
created until you Save the Document.
After a Work Item is created, you can edit its Description, and other attributes such as fields and links
provided that your user profile is granted permission to MODIFY Work Items, and Work Item fields.
If you are denied permission to modify any fields, you cannot edit Work Item content in the Document
Editor. You must use the Table view of the Work Items topic, where you will be able to modify only
those fields you have permission to modify. If you find you are restricted from editing Work Items, contact
your administrator to review your permissions.
Tip
To open a Work Item in the Table view, select it in the Document Editor, click its icon at the left
edge, and choose Open on the menu. You can also open the Table view form the Document Editor
toolbar.
• When you create a Work Item without a Title, Polarion creates one from the first 80 characters of the
Description.
• If you edit these first 80 characters, then the Title is also updated.
• If you enter your own Title, or edit the Description <after> the first 80 characters, Polarion assumes that
the Title is set and no longer updates it from the Description text.
You can change the Title and Description by opening the Work Item in Table or Tree view after you
Save it.
Creating hierarchically structured Work Items is as easy as using different indent levels. For
example suppose you have two paragraphs marked as Requirements, and the second paragraph
is a subrequirement of the first. Simply indent the second paragraph. Behind the scenes, Polarion
automatically takes care of linking the two Work Item artifacts with the correct link role, and people
viewing them in the integrated Tracker will see the links and the relationship.
If you change your mind and decide the two paragraphs are not hierarchical, simply unindent the child
paragraph and save the Document. Again, all linking operations of the underlying artifacts are handled
automatically. You simply keep working with your document.
Suppose you have two paragraphs marked as Requirements and you decide that the second Requirement
is neither a subrequirement, nor a separate requirement, but rather part of the first. Simply merge the
two paragraphs just as you would with paragraphs or bullet-list items in Word. The content of the second
Requirement is automatically unmarked as a Work Item, any structural linking is removed, and the content
appears as part of the first Requirement. If the Document was saved after the second Requirement was
created, then after the merge the underlying Work Item artifact is still maintained in the underlying
repository and appears in the Recycle Bin pane of the Document sidebar. This enables maximum
flexibility during the Document's development process. For example, you may later decide that a merged
Requirement actually belongs in a different Document. You could delete the relevant paragraph from the
combined Work Item, and move the original Work Item (now in the Document's Recycle Bin) to the
other Document. When the Document is near completion, you can clean up any Work Items in the
Recycle Bin that you are sure you no longer need. For information, see Recycle Bin.
You can also move content marked as a Work Item within the Document via Cut/Paste. It works just like
moving content in Word. Simply select the entire text of the marked Work Item, cut it to your clipboard,
and paste it back into the Document wherever you want it.
You can also modify the structure of the items using the Table view of the Work Items topic, which you
can open from the Document Editor toolbar.
Procedure
Note
If a Work Item is part of a Derived Document, Move is disabled in the Work Item editor. If you
select more than 20 items for Bulk Editing and want to Move selected items, then Work Items that
belong to Derived Documents are skipped.
Note
The Move operation moves any existing subtree, not just the selected item(s).
Both contained and Referenced Work Items can be moved within a Document using the Table
interface.
Note
Create Sibling Work Item is disabled via the Work Item editor if a Work Item is part of a Derived
Document.
1. Select an item in the Table view that is on the same hierarchical level as the new item you want to
create.
2. On the Work Item Editor toolbar click Create Sibling Work Item
3. On the submenu, select the Type for the new item. The menu enables you to select only the type(s)
configured for the Document that contains the currently selected Work Item. For example, if the
Document is configured to contain only Requirements, that will be the only submenu item. If it is
configured to contain Requirements and Tasks, both will appear as submenu items.
Users with the CREATE NEW Work Item and MODIFY CONTENT permissions for a Document and project
can easily copy one or more Work Items to another section of the same Document.
Tip
• Copying options are a little different when you copy Work Items to another Document.
• Just looking to move the same Work Item around in a Document? Use the Cut command
Images, diagrams and attachment previews within the Work Item(s) rich text fields (like the Description)
are also copied.
Procedure
1. Select a Document.
2. Highlight the text of the Work Item(s) to copy so it's highlighted in blue.
Tip
Don't see the Work Item type that you want in the list?
Cancel the copy, configure Work Item types and try again.
7. (Optional) Select if the new Work Item(s) should be linked to the original(s).
If so, you can select a link role from the drop-down menu.
• The Basic option will copy the Title, Description (including the images and diagrams within it) and
Test Steps.
• Advanced: Includes the Basic options plus the Priority, Severity, Links, Attachments, Custom
Fields and diagrams contained within the Work Item(s).
(The Status is always set to its initial workflow state for new Work Items, not the value of the
original Work Item.)
Tip
Click undo twice ( on the Document toolbar or Ctrl+Z) to undo new Work Item copies.
You can use the Cut command to move a Work Item to another place withing the same Document.
Note
• The same Work Item can only be Cut and placed in a different spot within the same Document.
Procedure
1. Select a Document.
2. Click on the icon of the Work Item you want to move and click Cut.
3. Click on the part of the Document that you want to move the Work Item to.
4. Right-click and click Paste (Or Ctrl+V).
Tip
You can use Undo on the Document toolbar or Ctrl+Z to restore the cut item to the Document.
Users with the CREATE NEW Work Item and MODIFY CONTENT permissions for a Document and project
can easily copy one or more Work Items to another Document.
When you copy Work Item(s) to another Document, you can create one of the following:
Images, diagrams and attachment previews within the Work Item(s) rich text fields (like the Description)
are also copied.
Tip
Copying options are a little different when you copy Work Items to the same Document.
Note
Multiple Work Item Types can be defined for the Document, but should be done before copying Work
Items.
Procedure
Note
• If you copy and paste one or more child Work Items, Polarion preserves their position as children
if you paste them under an existing Work Item.
• If you do not paste child Work Items under a Work Item, the first child Work Item becomes the
parent to preserve their structure.
The dotted line tells you it's a Referenced Work Item, not a copy.
(Optional) Select if the new Work Item(s) should be linked to the original(s).
If so, you can select a link role from the drop-down menu.
(Available link roles depend on the Work Item type selected and the link role configuration.)
b. Select what values to duplicate from the original. (They can be edited again later.)
• The Basic option will copy the Title, Description (including the images and diagrams within
it) and Test Steps.
• The Advanced option includes the Basic option plus the Priority, Severity, Links,
Attachments, Custom Fields.
(The Status is always set to its initial workflow state for new Work Items, not the value of the
original Work Item.)
Tip
Click undo twice ( on the Document toolbar or Ctrl+Z) to undo new Work Item copies.
(The first undo will change them to Referenced Work Item, and the second removes them.)
You can link the Work Items defined in a Document to other items in the same Document, in a
different Document, or stored directly in the Tracker. Links can denote structure and provide traceability.
For example, in a requirements specification Document, Requirement Work Items may be structured
with parent-child relationships where one item is the parent of one or more others. This type of structure is
most easily and naturally done with hierarchical headings and/or indentation — of paragraphs or list items,
for example. For information, see Structure a Document's Work Items.
Linking for traceability may require linking Work Items defined in one Document to Work Items defined in
a different Document, or created directly in the integrated Tracker. For example, you would probably want
to link Requirement Work Items defined in a requirements specification Document, to Test Case
items that verify the requirements. The Test Cases might be defined in another section of the same
Document, in another Document, or created directly in the Tracker. For more complete information, see
Link Work Items.
The following sections explain how to link Work Items to each other in the same Document, how to
link Work Items in one Document to items in a different Document, and how to link Work Items in a
Document to Work Items created directly in the Tracker.
Tip
No links are created in the system until you save the Document in which you originate the link(s). If you
accidentally create a pending link to the wrong target item, you can click the X icon in the link detail
panel and then confirm the prompt to cancel changes. You can then begin the linking operation again.
When linking to multiple Work Items, you can specify a different link role for different target items. For
example, you might link from a Requirement to a Test Case with a link role named Verifies,
and to another requirement with one named Refines. You select the link role in the Link Detailpanel
after clicking the link icon on each target Work Item.
You can link one Work Item in a Document to another single item, or several target Work Items in the
same Document all at once. For this operation, you only need one browser tab.
Procedure
1. Click on the icon in the left margin of the Work Item you want to link to some other Work Item.
The link detail panel appears.
2. In the link detail panel, select the link role for the link you are creating. This describes the relationship
of the source item to the target item(s) — relates to or depends on, for example.
3. Locate the first Work Item you are linking to, and click to the left of it.
If you want to link to multiple Work Items, hold down Ctrl (Windows) or Command (Mac and
others), and click the (Create Link) icon of each target Work Item. The panel reports the items
linked each time you click.
4. Save the Document. The links are not created in the repository or logged to the Document History
until you save.
You can view the items to which any Work Item is linked by clicking on the item in the Document and
opening the Work Item Properties pane of the Document sidebar.
You can link a Work Item in one Document to another single item in a different Document, or to several
target Work Items in a different Document all at once.
Tip
This linking is easiest if you open 2 browser tabs or windows: one displaying the Document containing
the Work Item(s) you want to link (referred to as Tab 1), and the other (Tab 2) displaying the Document
or Tracker view containing the Work Item(s) you want to link to.
Procedure
1. In one browser tab or window (Tab 1), open the Document containing the Work Item(s) you want to
link.
2. In a second browser tab or window (Tab 2), open the Document containing the target Work Item(s).
That is, the item(s) you want to link to from some item(s) contained in the first Document (in Tab 1).
3. In Tab 1, select a Work Item to link by clicking on the (Create Link) icon in the item's left margin.
The link detail panel appears in both browser instances.
4. In the link detail panel, select the link role for the link you are creating. This describes the relationship
of the source item to the target item(s)— Relates to or Depends on, for example.
5. Switch to Tab 2. If you want to link the item in Tab 1 to multiple items in Tab 2, press and hold Ctrl or
Command (depending on your operating system).
6. Click the (Create Link) icon beside the first target Work Item in Tab 2. To link to one or more
additional items in this target Document, click their link icons while continuing to hold down the Ctrl
or Command key.
7. Switch back to Tab 1 and save that Document (the one from which you started the link operation) to
create the links in the repository and Document history.
Tip
You can link new Work Items in a target Document as you create them. When you begin a link from
a Work Item in one Document (in Tab 1), then if you switch to a different Document (in Tab 2), and
you create new Work Items there, links to the new items are automatically created and added in the link
detail panel.
Tip
You can link a Work Item to one or more items in a historical revision of a target Document. For
example, you might link the current revision of a Business Case item to the version of a Requirement
in a functional specification Document that has been saved in a Project Baseline. To do this, open
in Tab 2 the Project Baseline containing the revision of the Document, and then open the Document
containing the items you want to link to.
You can link a Work Item contained in a Document to one or more Work Items created in the Tracker that
are not contained in any Document. You can link to a single target item, or multiple target items at once.
As in the previous section, you should use 2 browser tabs.
Procedure
1. In one browser tab (Tab 1), open the Document containing the Work Item(s) you want to link.
2. In a second browser tab (Tab 2), open the Table view (Navigation Work Items), and run a
query to retrieve the target Work Item(s) and list them in the table.
3. In Tab 1, select a Work Item to link by clicking the in the item's left margin. The link detail panel
appears in both browser instances.
4. Select the link role for the link you are creating. This describes the relationship of the source item to
the target item(s)— relates to or depends on, for example.
5. Switch to Tab 2. If you want to link the item in Tab 1 to multiple items in Tab 2, press and hold Ctrl or
Command (depending on your operating system).
6. In the table in Tab 2, locate the first target Work Item and click the on its row in the table. To link
to one or more additional items in the table, click the link icon on their respective table rows while
continuing to hold down the Ctrl or Command key.
Note
Each target item can be linked with a different link role. Change the role in the link detail panel
after Ctrl / Command clicking an item.
7. Switch back to Tab 1 and save the Document to create the links in the repository and Document
history.
Tip
You can link Work Items using other tools in the Polarionportal. You can use the Linked Work Items
section in the Work Item Editor (Navigation Work Items Table view). If your license
provides the feature, you can also link Work Items in the Matrix view.
See also:
• Link a resource
• Link individual Work Items
• Link multiple Work Items at once
• Link Work Items in the Matrix view
Use the Edit Links button in the Properties page of the Document sidebar to launch the Linked Work
Items dialog box. There, you can manage the links of the currently selected Work Item in your Document.
You can use the dialog box as an alternate way to add one or more links to a selected Work Item, as well
as to edit some properties of existing links, or remove some existing links. For details about this dialog,
please see Linked Work Items Dialog
The Document Sidebar provides the Work Item Properties sidebar, which enables you to edit data fields
and access links of Work Items defined in the Document.
You can specify which Work Item fields appear in the Properties section of the panel. When the
Properties panel is showing, click the icon (Pane Settings) icon and choose Select Fields on the
menu. In the Select Fields dialog box, select the check boxes of the Work Item fields you want to be able
to edit in the Document, and deselect those of fields that should not be shown there. You can also control
the order in which the fields display in the panel by rearranging their order in the dialog box.
Some Work Item fields, both default and custom, may be configured as required fields. A value must be
supplied in all required fields before a Work Item can be saved. When you mark a new Work Item in
a Document, if any required fields are not among those shown in the Work Item Properties sidebar,
then a default value is automatically and silently set for these fields. This default may or may not be what
you actually want, so it is usually a good idea to make sure that all required fields appear in Work Item
Properties panel of the Sidebar. You can easily see which fields are required by looking at any Work Item
in the Table view of the Document. Fields marked with a red asterisk (s) are required fields. Be sure to
check the Custom Fields section to see if any custom fields have been configured as required fields.
Tip
If a Work Item in a Document contains a custom field of type Table, the content of the field is only
editable in the Work Item Properties sidebar,. If the field does not appear there, you can add it, as
described above.
All the fields of any Work Item can be edited in the Table view of the Document, which you can
launch from the Document Editor toolbar. Remember also that you need user permissions that enable
you to edit Work Items and Work Item fields in order to change Work Item properties in a Document.
1. To access properties of a Work Item in a Document, click the Work Item's icon next to the left-hand
margin of the Document Editor.
2. On the menu that appears, choose Properties.
The Work Item Properties panel of the sidebar displays properties of the currently selected Work Item in
the Document. The data fields of the selected Work Item appear in the Properties section. Changes to
these fields do not take effect until you save the Document.
The Links section appears below the Properties section. It shows the items currently linked with the
selected Work Item.
Not all Work Items appearing in a Document are necessarily contained in it. Some may be contained
in another Document and just referenced in the current one. If the currently selected Work Item
is referenced from another Document, the Work Item Properties panel of the sidebar contains the
Documents section. That section lists the source Document — the one that actually contains the item,
and in which it can be edited — plus all Documents that reference the Work Item. Names of Documents
are clickable links that open the respective Documents in the Document Editor. For more information on
referenced Work Items, see Branch Documents and Work Item Properties sidebar.
Tip
If you find you cannot edit a Work Item, it may be referenced from a different Document. Check the
Work Item Properties panel. If the item is referenced, you can only modify it in the source Document,
and you must have the necessary permissions for editing Work Items and fields in that Document. If
Work Item not a referenced one, and you cannot edit it, you most likely lack the necessary permissions
for the current Document.
Whenever you mark Document content as a Work Item, Polarion creates a Work Item artifact in the
repository. Each Work Item artifact has a number of default data fields. It is also possible to configure
custom data fields. You can optionally show the value one or more Work Item data fields along with the
text of Document elements marked as Work Items. For example, you might decide to show such data
as status, priority, or assignee. When you configure data fields for the Work Item types in your Document,
Work Item data appears in your Document in Polarion, and in exported copies, but it is not really part
of the Document content. It is actually maintained in the underlying repository and simply displayed in
your Document. You can see the same fields in the Work Item detail if you view the item in the integrated
Tracker (Navigation Work Items Table, for example). Values for the ID and Status fields
are preconfigured to appear by default. You can either remove these from the visual presentation, or add
additional fields.
Procedure
1. Click the Work Item Type drop-down list control in the Document editor toolbar.
2. On the drop-down menu, choose Configure. The Configure Work Item Presentation dialog appears.
The dialog presents a table showing the Work Item types currently supported in the Document.
3. Locate the row for the Work Item Type you want to configure. For example, if the table contains
rows with presentation configurations for Requirement, Test Case, and Defect types, and you want to
specify the fields to show with Requirement type items, you will need to work with fields in the row
for Requirement.
4. Click the Select Fields button, and in the Select Fields dialog, add the fields you want to appear
in the Document from the list on the left to the list on the right. You can optionally set whether
to display fields at the start or end of Work Items. For more information, see Configure Work Item
Presentation Dialog.
Tip
The Select Fields dialog can also be invoked via the (Pane Settings) icon in the Work Item
Properties sidebar (enabled when a Work Item is selected in a Document). When invoked from
there, the fields configuration can be saved as a user-specific personal configuration only for the
current user, or as the default for the Document.
Related Topics
Document outline
Outline numbering can be applied to Document headings or Work Items in a Document. Outline
numbering in Polarion behaves similarly to outline numbering in Microsoft Word.
The outline numbering feature adds outline numbers to document headings. When Importing a Word
document, Outline numbering is enabled by default, but can be disabled before the actual import, as
described in the procedure below.
Procedure
Note
Prefix is only applied to Work Items within the heading, and is visible in Tree view of Work
Items.
5. Click the Save icon to save the Document and apply the changes.
Polarion can also automatically add outline numbers to all Work Items within a Document.
Procedure
1. Select an existing Work Item or locate the insertion point on an empty line.
2. Click the Work Item Type selector icon in the Document Editor toolbar.
3. Choose Configure. The Configure Work Item Presentation dialog box appears.
4. For every Work Item type in the table (there is one per row), click Select Fields. Then, in the Select
Fields dialog box, add Outline Number from the list of fields on the left to the list of fields on the
right.
5. (Optional) You can edit the order that the selected fields will appear using the keys. (The field
at the top of the list appears at the top of the table.)
6. Select a layout option:
• Show in Sidebar only: (Outline numbers only appear in the Document Properties, Work
Item Properties and Document Outline sidebars.)
• Show in Document only: Outline numbers only appear in the Document.
This only applies to the Work Item and Document sidebars. Outline Numbers always appear in the
Document Outline Sidebar.
• Show in Sidebar and document: (Outline numbers appear in both the document and respective
sidebars.)
(An additional Show at option appears letting you select whether to show the outline numbers
Before or After the Work Item.)
• Show Fields at End as Table: Displays any field with selected in a table at the end of the Work
Item.
7. Click Set as Default, then click OK .
You can optionally set a personal, user-specific preference for Work Item outline numbering if outline
numbering is not otherwise applied. In this case, you see outline numbers but other users do not.
Procedure
Note
The Reset button resets any field customization to the default settings.
When some Document content is marked as a Work Item, a Work Item artifact of a specified type is
created in the underlying repository. During editing of a Document, authors or editors may decide to
unmark some content so that it is no longer a Work Item, or (more likely) to merge one Work Item
paragraph or section into the preceding Work Item content. In such cases, the Work Item content
either no longer appears in the Document, or it no longer appears as a separate Work Item. However,
the artifact still exists in the underlying repository. This means that it is subject to workflow, planning,
auto-assignment, or any other Work Item and process management features and actions. In the early
stages of the Document's development, having such orphaned Work Items in a Document may be
perfectly acceptable because you might still want to do something with them — put them back into the
Document later, or put them into another Document, for example.
The Document sidebar's Recycle Bin panel shows any Work Items that exist in the repository, but are no
longer present in the Document. (You will also see these items in the Table view of the Document. This
view contains a button Open in Document's Recycle Bin which alerts any viewer to its state, as well as
providing access to it in the Recycle Bin.) The Recycle Bin provides you with some options for handling
these stored but unused Work Items. When you think a Document is complete, or nearing completion, it
is a good idea to check the Document's Recycle Bin and clean up any Work Items shown there so as not
to clutter the integrated tracker with Work Items that are not intended to be processed.
Prerequisites
Procedure
1. In the Document toolbar, click the sidebar icon to invoke a drop-down menu.
2. On the drop-down menu, choose Recycle Bin to display the sidebar's Recycle Bin sidebar.
The Recycle Bin sidebar provides several options for cleaning up Work Items in the Recycle Bin:
Tip
For Derived Documents, you can use the Recycle Bin to view Work Items that are no longer part of
the Document but cannot Insert, Move or Delete items.
(You can delete them using the Work Item detail form or tracker views like Table or Tree.)
Tip
For the procedures in the rest of this topic, you may find it useful to view: Recycle Bin sidebar.
For a reference on what actions send content to the Recycle Bin, see subtopic of the above: Content
Handling.
Procedure
1. Place the insertion point (caret) at the position where you want to insert the Work Item(s) currently
sitting in the Recycle Bin.
2. In the Recycle Bin, select the item(s) you want to insert by selecting the check box preceding the
ID-Title.
3. Click Insert to insert the selected Work Item(s) into the Document at the current insertion point.
You can move a Work Item from the Recycle Bin of one Document to a different Document.
Note
You must have permissions allowing you to modify the target Document and to create new Work Items
in it.
Procedure
1. In the Recycle Bin of the sidebar, select the item(s) you want to move by selecting the check box
next to each one.
5. In the Document list, select the name of the target Document, click OK, and finally Save the
Document.
The selected Work Items are disassociated from the current Document and removed from its Recycle
Bin. They are then associated with, and appended to the content of the target Document. If you
want the moved item(s) to appear elsewhere in the target Document, you need to open that
Document for editing and move them manually.
You can disassociate a Work Item in a Document's Recycle Bin from the Document but still keep it in the
project.
Procedure
1. In the Recycle Bin panel of the sidebar, select the item(s) you want to disassociate by selecting the
check box next to each one.
The selected Work Items are disassociated from the current Document and removed from the
Recycle Bin. However, the data artifacts are maintained in the repository with their same IDs and
properties. People using the integrated Tracker will be able to manage them as Tracker-based Work
Items.
You can delete Work Items from the Recycle Bin, disassociating them from the Document and deleting
them from the repository.
Note
Deleting a Work Item does not delete its history from the system.
Procedure
2. Click the Delete selected Work Items button and respond to the confirmation prompt.
Tip
You can also delete a Work Item without first moving it to the Recycle Bin: click the Work Item
icon in the left margin and select Delete on the menu. The item is deleted from the Document and
the repository. (It is not deleted from the Document History.)
If you want to delete a Work Item that is not defined in a Document, see Delete Work Items.
You can filter a Document to show only a subset of all the Work Items it contains. For example, a
specification might contain requirements for different operating systems. Assuming a custom field named
OS to designate the operating system, you could filter the Document to show only requirements for
Ubuntu Linux, for example, by querying on the custom field.
Filtering is accomplished using the integrated Apache Lucene query engine and query language. The
Visual Query Builder tool is available to help you construct simple or complex queries graphically, if you
are not familiar with the query language syntax.
1. On the Document toolbar, click Actions Filter. The Document becomes read-only, and filter
controls appear in the Document Editor toolbar.
2. In the Filter Work Items field, enter the visual query filters, query language syntax, or a combination
of the two as needed to obtain the results you want: OS:Ubuntu, or severity:must_have, for
example.
Tip
You can also filter Work Items when viewing any revision of a Document in the Document history.
If an item shown by the filter is the child of one or more other items, the parent items are also shown in
the Document regardless of whether or not they match the filter criteria.
While viewing the Document in its filtered state, you cannot edit the text. However, you can:
• Export the filtered Document using Word Round-trip Export Document. Only the Work Items
shown by the filtering are included in the exported document.
• Print the Document or export it to PDF. Only the Work Items shown by the filtering appear in the
printed copy or exported PDF file.
• Reply to any comment that is shown when the filtering is engaged (but not create new comments).
• Access linked Work Items that are hidden by the filter. Linked items appear in the Properties of Work
Items shown by the filter and if clicked, open in a new browser tab.
• Return to the unfiltered view of the Document by clicking Close Filter.
Documents Comments work in much the same way as in Microsoft Word and other desktop word
processing applications. Comments may be added to Documents either online in the portal, or in
Microsoft Word files that have been exported for comment and/or collaboration, and then reimported
using the Word Round-trip feature. You can add Documents Comments to the body text of your
Document or the Description of Work Items contained within it.
Documents Comments belong in the context of a Document and are not moved around or copied
with Work Items that reference them via the comment icon in the text. So, for example, when a
Document is Reused, Branched or a Work Item containing Document or Work Item Comments
is Duplicated, the comments are not copied. Polarion assumes that the source Document is already in
the final reviewed state with all comments resolved and incorporated into the Work Items and Document
text.
Tip
Review where Document and Work Item comments are preserved and where they are removed.
• The difference between Document and Work Item Comments and when they're Removed or
Preserved.
• Add a new Document Comment
• View existing Document Comments
• Reply to an existing Document Comment
• Delete a Document Comment
• Resolve, view hidden or Reopen Document Comments and Threads.
• Required Work Item comments
• Document Comments in Excel Round-trip
Caution
Document Comments should not be confused with Work Item Comments. They behave differently.
LiveDoc comments are used to help a Document through the approval process.
Where and when Document Comments and Work Item Comments are preserved:
Note
In Microsoft Word:
Removed Preserved
Append the Document
Document Comments in the Document you're
appending it to are Preserved.
Note
In order to add comments and Replies, or Resolve Comments, you must be assigned a user role that is
granted these permissions.
Procedure
An icon appears in the Document to highlight where the comment will go.
The Document body displays a icon at every point where a comment has been inserted.
Tip
• Click the icon to view it (and all other Document Comments) in the Comments sidebar.
You can use the comment reply feature to create threaded discussions inside a Document. To reply to an
existing comment, select the comment in the Comments sidebar and click Reply. A new comment
appears indented. Type your reply and click Save on the left side of the Document Editor toolbar.
Procedure
(Click on the Document Editor toolbar then Comments to launch the sidebar.)
Caution
If there are any replies to the comment you are deleting, they are also deleted.
When stakeholders reach a consensus through Comments and Comment threads, it can be useful to
mark the comments and/or comment threads as Resolved. This hides them, after which individual users
can opt to view them. It is also possible to reopen resolved comments if a stakeholder decides that further
discussion is needed.
Procedure
1. Click on the Document Editor toolbar then Comments to launch the sidebar.
2. Locate the comment to mark as resolved, hover your pointer over it, and click Resolve.
(In comment threads, you must mark the top-level comment.)
Procedure
1. Click on the Document Editor toolbar then Comments to launch the sidebar.
Procedure
1. Click on the Document Editor toolbar then Comments to launch the sidebar.
3. Locate the resolved comment you want to reopen, hover over it and click Reopen.
Note
Replying to any comment in a resolved thread reopens the entire thread.
See also: Resolve Approval Comments, Resolve Work Item Comments and Threads and
Signature Comments.
Only Document comments are accessible in the Document Editor, but it is possible for administrators to
configure projects to make the Comments field of Work Items a required field. When they do, Work Item
changes that affect the workflow cannot be saved without adding a comment to the Comments field. This
prevents Document users from saving the Document if they change a field such as Status via the Work
Item Properties sidebar, because the Comments field is not accessible in the Document Editor.
Tip
Administrators and project leaders should inform their users and teams if Work Item Comments are
required to transition the workflow.
If you are prompted to add a Work Item Comment after changing the Status in one or more of the
Document's Work Items, it means you cannot change Status in the Document Editor. You will instead
need to use the Table view of the Document. (On the top right of the Document Editor toolbar).
In this situation, if you have unsaved content changes, go back to all the Work Items that you changed
the Status for, and set the value back to what it was before you changed it. You should then be able to
Save your changes. If you have no pending content changes, you just can switch to Table view
immediately and opt to cancel changes when prompted.
In the Table view, browse or run a query to find the Work Items that you want to change the Status
for. For each item, change the Status field as desired and add a new Work Item Comment.
If Work Items containing Document Comments are exported for Excel round-trip, and the Work Item
Description field is allowed by the exporting user to be editable in the exported Excel workbook, a
placeholder {comment:id} is inserted into description text in the exported Excel workbook.
Caution
The {comment:id} placeholder preserves the comment marker for the round-trip process and should
not be removed from the exported Excel document.
After inserting an image or attachment preview, you can add a caption above or below it, resize it, or
launch a full screen preview of it.
Note
Your system or project administrator can optionally limit the file size of attachments. Contact your
administrator if you are unable to upload an attachment due to such restriction.
Download an attachment
Procedure
1. Open the Attachments panel of the Document Sidebar if it is not already open.
2. Locate the attachment you want to update. Optionally use the search box at the top of the panel.
3. Hover your pointer over the attachment you want to download and click the icon.
4. If prompted by your browser, select the location on your local file system where you want to store the
downloaded file, and confirm the save action. Otherwise, you can look for the downloaded file in the
location where your browser stores downloads.
Update an attachment
Procedure
1. Open the Attachments panel of the Document Sidebar if it is not already open.
2. Locate the attachment you want to update. Optionally use the search box at the top of the panel.
3. Hover your pointer over the attachment you want to update and click the (Update) icon.
4. Locate the updated version of the attachment file in your local file system, select it, and confirm your
selection in your file selection dialog.
Note
The file you upload should have the same file name and extension as the existing attachment. If
you upload a different extension, you are asked if you wish to overwrite the existing attachment.
5. After the selected file uploads, save the Document to complete the attachment update.
Delete an Attachment
Procedure
1. Open the Attachments panel of the Document Sidebar if it is not already open.
2. Locate the attachment you want to delete. Optionally use the search box at the top of the panel.
3. Hover your pointer over the attachment you want to delete and click the (Delete) icon .
4. Save the Document to complete the delete operation.
Tip
If you delete the wrong attachment by mistake, you can click Undo on the Document Editor
toolbar, provided you did not yet save the Document. If you did save it, you can revert the
Document to the previous revision in the History.
You can easily search Work Items to find all that have some kind of attachment. You can refine the
search to include only items with attachments of specified file type(s), and also filter selected attachments
according to:
• Title
• File name
• Author
• File size
• Date modified
• Content (provided that indexing of attachment content is enabled in the system configuration - see
Advanced System Tuning).
To query for attachments in the Tableview of Work Items, click the icon in the Query Builder,
select one of the query elements beginning with the word Attachment, and select appropriate criteria for
the element. Add additional Attachment elements to further refine the query. For more information on
queries, see Search Work Items.
If you're linking a Polarion artifact like a Work Item, then the Live Link displays the item's Status
or Severity ( ) and will dynamically update if, for example, the Status is closed
.
Caution
Copying and pasting Live Links is different for Microsoft Edge.
• Live Links linked to Historical revisions or Document Baselines are linked to the item in that specific
revision and contain the icon.
• If the link contains parameters like a Work Item in edit mode or a document with filters applied, then it
will become a portal link.
Tip
If you're looking to link Headings or Work Items within a Document you should use Cross-references
instead. Not sure whether to use a Live Link or a Cross-references? Learn the difference.
You can insert a Live Link via the button or by using paste.
Procedure
1. Click where you want to place the link within your Document or rich text field.
2. Click on the drop-down widget beside Insert Image or Attachment Preview on the Document
or rich text field's toolbar, then click Link or Cross-reference.
The Insert Link or Cross-reference dialog box appears.
3. Paste your link into the URL field and click Next.
If you pasted a Polarion artifact link, you select whether to include or exclude the title or add your
own Custom Label.
(If you selected Custom Label, enter your text in the field and click Insert.)
The link is inserted within the Document or rich text field.
Procedure
1. Click where you want to place the link within your Document or rich text field.
2. Press Ctrl+V or right-click and click Paste.
The Insert Link as dialog box appears.
3. (Optional) Click Show Advanced if you want to change the pasted URL.
a. The Update Link or Cross-reference dialog box appears.
b. Change the URL or click Custom Label, enter the label you want and click Update.
(If it's a link to a Polarion Work Item, you'll also have the option to include or exclude its title.)
The Live Link dialog box does not appear by default when you copy at Polarion link from the address bar
with Microsoft Edge v87+ and a link with an icon does not appear when you paste it back into Polarion.
• Full/URL/links/to/the/Document
Instead of:
Tip
If you want Live Links copied from the address bar to appear as intended in Microsoft Edge, do one of
the following:
• Paste Live Links taken from the address bar with the Ctrl +Shift +V keyboard shortcut.
• Edit Edge's settings, so that Paste links as plain text is the default behavior.
Insert a caption
2. For Work Items: Click Edit on the top left or on the Description tab.
3. Select the Image, Table, or Diagram to add a caption to.
Note
For diagrams, Click the icon that appears when you mouse-over your target.
6. (Optional) Select if you want the caption to appear Above or Below (default) the artifact.
7. (Optional) Select the type of Label to use. (Figure, Table, or click New Label to enter a custom
label.)
8. Click Add. The caption appears for your selected artifact.
Why would you add a Custom Label? You might, for example, create a label named Citation and specify it
when adding a caption to some items. You could then insert a Table of Citations in your Document.
Note
Tables of figures, tables of tables, and tables of custom-labeled items appear only in documents
generated by export to PDF and Round-trip for Microsoft Word. A placeholder appears in your Polarion
Document.
A custom caption label appears in the Label list when the Document contains a caption that uses it.
To remove a custom label, remove all captions that use it and refresh your browser.
When on-demand Work Item loading is enabled by administrators in the system configuration it affects
captions as follows:
• If the Document's Work Item Presentation configuration is set up for Test Steps or rich-text type
Custom Fields to be visible, then all caption numbers appear as a hash mark (#). They are replaced with
the correct numbers when exported.
• If the Document's Work Item Presentation configuration does not contain Test Steps or Custom
Fields as outlined above, then caption numbers will display, even with on-demand Work Item loading
enabled.
Visible caption numbers will display correctly even if previous captions from the same sequence have
not finished loading.
When on-demand Work Item loading is disabled, then all caption numbers will appear in the Document,
but they may take a while to load if the Document is a large one with many Work Items and/or captioned
content.
There are two default caption label values: Table and Figure. These values determine if a caption is
included in a Table of Figures or a Table of Tables, if these are inserted into a Document.
Insert a Cross-reference
Cross-references let you link to Headings or Work Items within a Document. When clicked, they scroll
right to their target.
To distinguish them from Live Links, cross-references are underlined with a dashed gray line:
Note
• Unlike Live Links, cross-references are only navigational links and do not reflect an item's Status or
Severity.
Tip
Always use the method above to copy cross-references. If you copy them any other way, they may
not work as expected.
3. Press Ctrl+C, or the equivalent copy-to-clipboard shortcut for your operating system, when the Copy
to Clipboard dialog box appears.
4. Scroll to, and click where you want to place the cross-reference.
5. Press Ctrl+V.
A cross-reference can be added to the Document's body text or to the fields of a Work Item
contained within the Document.
7. Click to keep the default outline numbers and title, or select the options to omit the title or replace
the outline numbers with the Project ID.
Tip
Click Custom Label to define your own cross-reference link text.
Note
• If a referenced Work Item or Heading is removed, any cross-references pointing to it change to
Missing cross-reference.
(It also contains the missing item's ID, so that it can be easily tracked down.)
• If the referenced item is filtered out of the Document, then the cross-reference link remains but does
not scroll when clicked.
• Cross-references created in Polarion will survive a Word Round-trip, but instead of scrolling in the Word
document, they open the referenced object in Polarion.
• Cross-references created in Word are not recognized when imported into Polarion.
Warning
Cross-references contained in Polarion Work Items are lost when those Work Items are exported to
Microsoft Excel for round-trip. This is due to limitations in Excel, and there is no work-around. If a
round-trip workbook to which cross-references were exported is subsequently re-imported, the original
cross-references in Polarion will no longer work, and must be manually restored. Always check for
cross-references in Work Items you plan to export to Excel for round-trip. Either avoid exporting items
containing cross references, or plan to repair them after round-trip operations are completed.
Tip
You need a PDF reader application to view PDF documents.
• If a cross-referenced item exists within the same PDF, then clicking its cross-reference scrolls right to it.
• If a cross-referenced item is not within the PDF, then clicking its cross-reference opens the item in the
Document Editor in Polarion.
• If a Document was filtered before it was exported, cross-references for filtered items are exported as
plain text.
(They do not scroll to, or open the items in Polarion when clicked.)
• Cross-reference links are underlined with a solid black line in exported PDFs
• When a Live Link is created, then clicking Heading or Work Item icon Copy Link opens the
linked item in the Work item Editor.
• If a cross-reference is pointed to a section within a master Document, it will point to its matching
counterpart section in Branched or Variant or Reused versions.
• If a referenced Work Item that is targeted in a cross-reference is overwritten, the cross-reference is
updated so that it still scrolls to the same position.
• When a Work Item is opened in the Work Item Editor, any cross-reference contained within it link to
the master Document.
• If you change the title of a cross-referenced Heading or Work item, the cross-reference link text updates
accordingly.
(But only within the Document version in that the Heading is changed in.)
Note
Currently cross-references between Documents, Revisions and Baselines is not fully supported and
cannot be rendered as Live Links.
You can repair missing cross-references by inserting the missing item using the Insert Live/Frozen
reference merge action.
Insert a Diagram
You can use the Diagram Editor to create and edit diagrams. You create them in a Document, Work
Items within Documents and Work Item fields like the Description.
Note
See the Known issues and limitations for diagrams before you get started.
When you create or edit a Diagram three files are added to your Document's Attachments sidebar or
Work Item's Attachments section.
• diagram_[number].mxg
The file used by the Diagram Editor (draw.io) to store information for further editing.
• diagram_[number].mxg.png
A Portable Network Graphic (PNG) version that is only used when you export a Document to PDF or
Microsoft Word.
(The files are stored within a Work Item's Attachments section when a diagram is added to their
Description.)
• diagram_[number].mxg.svg
The Scalable Vector Graphics (SVG) version that appears in your Document or Work Item.
You can add Mathematical Formulas to a Document or Work Item rich text field.
Tip
• See Syntax help for a list of supported symbols and examples.
• You can use third-party software or an online editor to create a formula and copy and paste the
LaTeX syntax they output into Polarion.
Caution
Microsoft Word formulas must be saved in Professional mode to import correctly into Polarion.
• In Documents:
◦ ReqIF: Not supported
◦ Microsoft Word RoundTrip: Appear as images in Word, but can be edited by importing them back
into Polarion.
(You need to replace them to edit them in Word, but the Word formulas will be editable if imported
back into Polarion.)
◦ PDF: The formulas are rendered as images
Procedure
1. Open the Document or Work Item field that you want to edit.
2. Click where you want to insert a formula.
• In a Document, choose Mathematical Formula on the Insert menu of the Document Editor
toolbar:
Tip
If your formula does not render as expected, click Syntax help to view a list of supported symbols
and examples.
6. Click Insert. The formula is inserted into the Document or Work Item field.
Procedure
1. Open the Document or Work Item field that contains the formula you want to edit.
2. Select the formula and click Edit. (Or double-click the formula.)
3. Edit the formula in the Formula in LaTeX field, and check the preview to ensure that it's correct.
4. Click Update.
You can find extensive resources on the MathJax library for LaTex syntax at the following external sites:
• https://docs.mathjax.org/en/latest/input/tex/macros/index.html
• https://www.onemathematicalcat.org/MathJaxDocumentation/TeXSyntax.htm
Caution
The external links may contain some commands from versions of MathJax that are not supported in
Polarion.
Tip
You can use third-party software or an online editor to create a formula and copy and paste the LaTeX
syntax they output into Polarion.
Examples
|x| =
\begin{cases}
x & \text{ if } x\ge 0 \\
-x & \text{ if } x \lt 0
\end{cases}
\left( \sum_{k=1}^n a_k b_k \right)^2
\leq
\left( \sum_{k=1}^n a_k^2 \right)
\left( \sum_{k=1}^n b_k^2 \right)
A = \pmatrix{
a_{11} & a_{12} & \ldots & a_{1n} \cr
a_{21} & a_{22} & \ldots & a_{2n} \cr
\vdots & \vdots & \ddots & \vdots \cr
a_{m1} & a_{m2} & \ldots & a_{mn} \cr
}
{\frac {d}{dx}}\arctan(\sin({x}^{2}))=-2\,{\frac
{\cos({x}^{2})x}
{-2+\left (\cos({x}^{2})\right )^{2}}}
\begin{cases}
\lim\limits_{x \to \infty} \exp(-x) = 0\\
k_{n+1} = n^2 + k_n^2 - k_{n-1}\\
a \bmod b,x \equiv a \pmod{b}\\
\frac{n!}{k!(n-k)!} = \binom{n}{k}\\
\end{cases}
\frac{
\begin{array}[b]{r}
\left( x_1 x_2 \right)\\
\times \left( x'_1 x'_2 \right)
\end{array}
}{ \left( y_1y_2y_3y_4 \right) }
\int\limits_a^bP\left(A=2\middle|\frac{A^2}
{B}>4\right)>\int_0^\infty \mathrm{e}^{-x}
\,\mathrm{d}x
\left\{\frac{x^2}{y^3}\right\}\to
\left.\frac{x^3}{3}\right|_0^1\to
\big( \Big( \bigg( \Bigg(
\frac{\mathrm d}{\mathrm d x} \left( k g(x) \right)
\Bigg) \bigg) \Big) \big)
M = \begin{bmatrix}
\frac{5}{6} & \frac{1}{6} & 0 \\[0.3em]
\frac{5}{6} & 0 & \frac{1}{6} \\[0.3em]
0 & \frac{5}{6} & \frac{1}{6}
\end{bmatrix}
\left(
\begin{array}{c} n \\ r
\end{array}
\right) = \frac{n!}{r!(n-r)!}
\begin{cases}
B'=-\nabla \times E,\\
E'=\nabla \times B - 4\pi j,\\
F\colon X \rightarrow Y \\
x \mapsto 2x
\end{cases}
Symbols
' f'(x)
_ a_b subscript
{ \frac{1}{2}
} \frac{1}{3}
\ a\ b
\#
\$
\%
\&
\\ line separator
\_
\{
\|
\}
\abovewithdelims a \abovewithdelims
[ ] 1pt b
\acute \acute a
\aleph
\alpha
\amalg
\And
\angle
\approx
\approxeq
\arccos
\arcsin
\arctan
\arg
\Arrowvert
\arrowvert
\ast
\asymp
\atop a \atop b
\atopwithdelims a \atopwithdelims
[]b
\backprime
\backsim
\backsimeq
\backslash
\bar \bar{a}
\barwedge
\Bbb \Bbb Q
\Bbbk
\bbox \bbox[10px]{math}
\bcancel \bcancel{X^2}
\because
\begin \begin{matrix} -1
& 3 \\ 2 &
-4\end{matrix}
\begingroup
\beta
\beth
\between
\bf
\Big \Big(x\Big)
\big \big(x\big)
\bigcap
\bigcirc
\bigcup
\Biggl
\biggl
\Biggm
\biggm
\Biggr
\biggr
\Bigl \Bigl(x\Bigr)
\bigl \bigl(x\bigr)
\Bigm
\bigm
\bigodot
\bigoplus
\bigotimes
\Bigr \Bigl(x\Bigr)
\bigr \bigl(x\bigr)
\bigsqcup
\bigstar
\bigtriangledown
\bigtriangleup
\biguplus
\bigvee
\bigwedge
\binom \binom a b
\blacklozenge
\blacksquare
\blacktriangle
\blacktriangledown
\blacktriangleleft
\blacktriangleright
\bmod
\boldsymbol \boldsymbol{x}
\bot
\bowtie
\Box
\boxdot
\boxed \boxed{x}
\boxminus
\boxplus
\boxtimes
\brace
\bracevert
\brack
\breve \breve{x}
\cancelto \cancelto{some}
{text}
\cap
\Cap
\cee \cee{x}
\centerdot
\cf \cf{x}
\cfrac \cfrac{x}{y}
\check \check{X}
\checkmark
\chi
\choose
\circ
\circeq
\circlearrowleft
\circlearrowright
\circledast
\circledcirc
\circleddash
\circledR
\circledS
\class
\clubsuit
\colon
\color \color{red}
{\text{red text}}
\colorbox \require{color}
\colorbox{yellow}{$
\sigma$}
\complement
\cong
\coprod
\cos
\cosh
\cot
\coth
\csc
\cssId
\cup
\Cup
\curlyeqprec
\curlyeqsucc
\curlyvee
\curlywedge
\curvearrowleft
\curvearrowright
\daleth
\dashleftarrow
\dashrightarrow
\dashv
\dbinom \dbinom{2}{3}
\ddagger
\ddddot \ddddot a
\dddot \dddot a
\ddot \ddot a
\ddots
\DeclareMathOpera \DeclareMathOpera
tor tor{\dec}{\int}
\dec_a^b
\definecolor \require{color}
\definecolor{Bright
Green}{rgb}{0.4,
1.0, 0.0}
\color{BrightGreen}
{text}
\def
\deg
\Delta
\delta
\det
\dfrac
\diagdown
\diagup
\diamond
\Diamond
\diamondsuit
\digamma
\dim
\displaylines \displaylines{ a + b
= 0 \cr a = 1 }
\displaystyle
\div
\divideontimes
\dot \dot a
\doteq
\Doteq
\doteqdot
\dotplus
\dots
\dotsb
\dotsc
\dotsi
\dotsm
\dotso
\doublebarwedge
\doublecap
\doublecup
\Downarrow
\downarrow
\downdownarrows
\downharpoonleft
\downharpoonright
\emptyset
\enclose
\end
\endgroup
\enspace
\epsilon
\eqalign
\eqalignno
\eqcirc
\eqref
\eqsim
\eqslantgtr
\eqslantless
\equiv
\eta
\eth
\exists
\exp
\fbox
\fcolorbox
\Finv
\flat
\forall
\frac
\frac
\frak
\frown
\Gamma
\gamma
\gcd
\gdef
\ge
\genfrac
\geq
\geqq
\geqslant
\gets
\gg
\ggg
\gggtr
\gimel
\global
\gnapprox
\gneq
\gneqq
\gnsim
\grave
\gt
\gtrapprox
\gtrdot
\gtreqless
\gtreqqless
\gtrless
\gtrsim
\gvertneqq
\hbar
\hbox
\hdashline
\heartsuit
\hline
\hom
\hookleftarrow
\hookrightarrow
\hphantom
\href Not supported
\hskip
\hslash
\hspace
\Huge
\huge
\idotsint
\iiiint
\iiint
\iint
\Im
\imath
\impliedby
\implies
\in
\inf
\infty
\injlim
\int
\intercal
\intop
\iota
\it
\Join
\ker
\kern
\lambda
\land
\langle
\LARGE
\Large
\large
\LaTeX
\lbrace
\lbrack
\lceil
\ldotp
\ldots
\le
\leadsto
\left
\Leftarrow
\leftarrow
\leftarrowtail
\leftharpoondown
\leftharpoonup
\leftleftarrows
\Leftrightarrow
\leftrightarrow
\leftrightarrows
\leftrightharpoons
\leftrightsquigarro
w
\leftroot
\leftthreetimes
\leq
\leqalignno
\leqq
\leqslant
\lessapprox
\lessdot
\lesseqgtr
\lesseqqgtr
\lessgtr
\lesssim
\let
\lfloor
\lg
\lgroup
\lhd
\lim
\liminf
\limits
\limsup
\ll
\llap
\llcorner
\Lleftarrow
\lll
\llless
\lmoustache
\ln
\lnapprox
\lneq
\lneqq
\lnot
\lnsim
\log
\Longleftarrow
\longleftarrow
\Longleftrightarrow
\longleftrightarrow
\longmapsto
\Longrightarrow
\longrightarrow
\looparrowleft
\looparrowright
\lor
\lower
\lozenge
\lrcorner
\Lsh
\lt
\ltimes
\lVert
\lvert
\lvertneqq
\mapsto
\mathbb
\mathbf
\mathbin
\mathcal
\mathchoice
\mathclose
\mathfrak
\mathinner
\mathit
\mathop
\mathopen
\mathord
\mathpunct
\mathrel
\mathring
\mathrm
\mathscr
\mathsf
\mathstrut
\mathtip
\mathtt
\matrix \matrix{ a & b \cr c
&d}
\max
\mbox
\measuredangle
\mho
\mid
\middle
\min
\mit
\mkern
\mmlToken
\mod
\models
\moveleft
\moveright
\mp
\mskip
\mspace
\mu
\multimap
\natural
\ncong
\ne
\nearrow
\neg
\negmedspace
\negthickspace
\negthinspace
\neq
\newcommand
\newenvironment
\Newextarrow
\newline
\nexists
\ngeq
\ngeqq
\ngeqslant
\ngtr
\ni
\nLeftarrow
\nleftarrow
\nLeftrightarrow
\nleftrightarrow
\nleq
\nleqq
\nleqslant
\nless
\nmid
\nobreakspace
\nolimits
\normalsize
\not
\notag
\notin
\nparallel
\nprec
\npreceq
\nRightarrow
\nrightarrow
\nshortmid
\nshortparallel
\nsim
\nsubseteq
\nsubseteqq
\nsucc
\nsucceq
\nsupseteq
\nsupseteqq
\ntriangleleft
\ntrianglelefteq
\ntriangleright
\ntrianglerighteq
\nu
\nVDash
\nVdash
\nvDash
\nvdash
\nwarrow
\oint
\oldstyle
\Omega
\omega
\omicron
\ominus
\operatorname
\oplus
\oslash
\otimes
\over
\overbrace \overbrace{a+
\cdots+a}^{n\text{ t
imes}}
\overleftarrow \overleftarrow {ab}
\overleftrightarrow \overleftrightarrow
{ab}
\overline \overline {ab}
\overrightarrow \overrightarrow
{ab}
\overset \overset {a} {b}
\overwithdelims
\owns
\partial
\perp
\phantom
\Phi
\phi
\Pi
\pi
\pitchfork
\pm
\pmb
\pmod
\pod
\Pr
\prec
\precapprox
\preccurlyeq
\preceq
\precnapprox
\precneqq
\precnsim
\precsim
\prime
\prod
\projlim
\propto
\Psi
\psi
\rbrace
\rbrack
\rceil
\Re
\ref
\renewcommand
\renewenvironmen
t
\require
\restriction
\rfloor
\rgroup
\rhd
\rho
\right
\Rightarrow
\rightarrow
\rightarrowtail
\rightharpoondown
\rightharpoonup
\rightleftarrows
\rightleftharpoons
\rightleftharpoons
\rightrightarrows
\rightsquigarrow
\rightthreetimes
\risingdotseq
\rlap
\rm
\rmoustache
\Rrightarrow
\Rsh
\rtimes
\Rule
\rVert
\rvert
\scr
\scriptscriptstyle
\scriptsize
\scriptstyle
\searrow
\sec
\setminus
\sf
\sharp
\shortmid
\shortparallel
\shoveleft
\shoveright
\sideset
\Sigma
\sigma
\sim
\simeq
\sin
\sinh
\skew
\small
\smallfrown
\smallint
\smallsetminus
\smallsmile
\smash
\smile
\Space
\space
\spadesuit
\sphericalangle
\sqcap
\sqcup
\sqrt
\sqsubset
\sqsubseteq
\sqsupset
\sqsupseteq
\square
\stackrel
\star
\strut
\style
\subset
\Subset
\subseteq
\subseteqq
\subsetneq
\subsetneqq
\substack
\succ
\succapprox
\succcurlyeq
\succeq
\succnapprox
\succneqq
\succnsim
\succsim
\sum
\sup
\supset
\Supset
\supseteq
\supseteqq
\supsetneq
\supsetneqq
\surd
\swarrow
\tanh
\tau
\tbinom
\TeX
\text
\textbf
\textit
\textrm
\textsf
\textstyle
\texttt
\texttip
\tfrac
\therefore
\Theta
\theta
\thickapprox
\thicksim
\thinspace
\tilde \tilde a
\times
\tiny
\Tiny
\to
\toggle
\top
\triangle
\triangledown
\triangleleft
\trianglelefteq
\triangleq
\triangleright
\trianglerighteq
\tt
\twoheadleftarrow
\twoheadrightarro
w
\underbrace \underbrace{a+
\cdots+a}_{n\text{ t
imes}}
\underleftarrow
\underleftrightarro
w
\underline
\underrightarrow
\underset
\unicode
\unlhd
\unrhd
\Uparrow
\uparrow
\Updownarrow
\updownarrow
\upharpoonleft
\upharpoonright
\uplus
\uproot
\Upsilon
\upsilon
\upuparrows
\urcorner
\varepsilon
\varGamma
\varinjlim
\varkappa
\varLambda
\varliminf
\varlimsup
\varnothing
\varOmega
\varphi
\varPhi
\varpi
\varPi
\varprojlim
\varpropto
\varPsi
\varrho
\varsigma
\varSigma
\varsubsetneq
\varsubsetneqq
\varsupsetneq
\varsupsetneqq
\vartheta
\varTheta
\vartriangle
\vartriangleleft
\vartriangleright
\varUpsilon
\varXi
\vcenter
\vdash
\Vdash
\vDash
\vdots
\vec
\vee
\veebar
\verb
\Vert
\vert
\vphantom
\Vvdash
\widehat
\widetilde
\wp
\wr
\xi
\xcancel
\xleftarrow
\xlongequal
\xmapsto
\xrightarrow
\xtofrom
\xtwoheadleftarro
w
\xtwoheadrightarro
w
You can insert a table of contents (TOC) into a Document. The content of the TOC is based on the
headings in the Document. If you insert a TOC into a Document that has no headings, the message
No table of contents entries found appears at the point you insert the TOC. The TOC is
automatically updated when you add new headings and save the Document. TOC items are links which
scroll the page to the respective heading. You can explicitly update or delete the Document's TOC any
time, and you can insert a new paragraph before or after the TOC.
The Document Editor allows up to 29 heading levels, but the TOC in a Document only displays up to 5
heading levels.
Tip
You can Update the TOC in an exported Microsoft Word version so that up to 9 heading levels are
visible in the Word document.
Procedure
1. Place the insertion point (caret) at the position in the Document where you want to insert the TOC.
2. In the toolbar, click the Insert drop-down (see figure below) and choose Table of Contents. The
TOC is inserted and the (Table of Contents) icon appears outside the Document's border.
The Document TOC is updated automatically when you save the Document. However, you can explicitly
update it while editing the Document.
Note
Procedure
2. Click Update.
Procedure
You can insert a new paragraph before or after the Table of Contents in a Document.
Procedure
1. To insert a Table of Figures in a Document, click the Insert drop-down, select Table of
Figures.
The inserted table includes links to images and/or diagrams in the Document that have a caption with the
caption label Figure. For more information, see reference topic Captions.
Note
The Table of Figures appears only in documents created by export to PDF and Round-trip for Microsoft
Word. A placeholder appears in your Polarion Document.
The procedure to insert a Table of Tables is identical to that for inserting a Table of Figures, except that
you choose a different caption label option.
Procedure
3. The inserted table includes links to tables in the Document that have a caption with the caption label
Table. For more information, see the Captions reference topic.
In Documents, it is possible to insert textual content formatted with Classic Wiki syntax, or Classic Wiki
macros which render content dynamically. For example, you might create a Document that reports the
current status of Work Items in the project using the {workitems} macro with a query parameter to
display some subset of the Work Items in the Document — all currently Open items, or items with high
Severity, for example.
Procedure
1. In the Document Editor toolbar, click the insert drop-down and click Wiki Content.
2. Add your Classic Wiki macro or other content with Classic Wiki mark-up to field, and click OK.
Tip
Not familiar with Wiki syntax? Click Syntax Help in the dialog box.
You can modify existing embedded wiki content. For example, you might modify the query of an existing
workitems macro to retrieve a different set of Work Items, or display more or fewer Work Item fields.
Procedure
1. After locating the content you want to modify, click the Wiki Content icon on the left margin.
2. On the menu, click Modify to display the Wiki Content dialog box.
3. Edit the content and click OK.
• After locating the content you want to modify, click the Wiki Content icon on the left margin, then
click Delete.
You can insert explicit Page Breaks in a Document. These breaks also occur in exported documents
after export to PDF and Microsoft Word Round-trip.
Procedure
1. Place the insertion point inside of the paragraph that's just before where you want to insert a Page
Break, or on an empty line.
The icon appears outside the Document border where the Page Break occurs in the exported
content.
To change this orientation, Click the icon and select the Orientation you want to apply to the
above section.
The Page Break icon changes to and if exported again via a Word Round-trip, the section/page
above is landscape-oriented.
Note
Page Breaks set the orientation of the sections above them. (A Page Break at the end of a section
sets the orientation for that section.)
What to do next
Tip
You can't have a Document with both portrait and landscape pages when exporting directly to PDF from
Polarion.
(Orientation for the entire Document is selected during the PDF export process.)
Recommendation: Export the Document via Word Round-trip, then save as PDF in Word.
Insert a Table
Insert Table lets you add a table to your Document and edit it like you would in other rich text
editors.
Procedure
4. Click OK.
5. (Optional) Adjust column or row sizes, add rows or a caption.
• Hover over a row or column's border line, hold down the left mouse button and adjust their size.
• Select the bottom row and hold down Tab to create multiple rows below the selected row.
• Click within a table cell, then Add Row or Add Caption.
Note
• If there's a long word in a table cell, it's wrapped by default and divided once its characters reach the
defined borders.
In some cases, for example, if a table column is only a couple of characters wide, this makes the text
hard to read.
• System Administrators can set the following property to false in the polarion.properties file to
disable the default word wrap and enable tables to overflow LiveDoc borders.
com.siemens.polarion.ui.documents.table.breakWord.enabled=false
(Search for the property in System Configuration Properties Reference document for more
information.)
• Cut Rows: Hold down CTRL, select rows, and click Cut Rows to remove them.
• Copy Rows: Hold down CTRL, select rows, and click Copy Rows to add them to your clipboard.
• Paste Rows: Click in the row you want to paste copied rows after, and click Paste Rows.
• Insert...
◦ Column to the Left: Inserts a column to the left of your selected cursor position.
◦ Column to the Right: Inserts a column to the right of your selected cursor position.
◦ Row Above: Inserts a row above your selected cursor position.
Resolve conflicts
When any user saves changes to a Document, Polarion attempts to merge concurrent changes, and
does so silently when it is clear that it is safe, and no other user's changes will be overwritten. If there's a
case where some changes might be lost, a warning appears describing the potentially conflicting changes.
It summarizes the issues, provides some explanatory help text, and provides links that open separate
browser tabs where the user can review their pending changes, and the changes of other users.
• A dialog appears, warning that changes cannot be safely merged, so some changes from other users will
be overwritten.
Tip
All Document revisions are automatically saved in the History. If some changes are overwritten
by mistake, it is always possible to copy the "lost" content from the historical revision where it was
present, and paste it to the current revision of the Document.
The easiest way to understand how Polarion deals with concurrent changes to a Document is to learn
what it considers a top-level element and how it searches for concurrent changes.
Polarion divides the page horizontally based on the top-level elements (listed below).
Top-level elements that span an entire line of a Document and trigger a merge warning when the
second set of changes is Saved.
(Any concurrent changes trigger a merge warning when the second set of changes is Saved.)
An Image and Diagram on the same line are treated as a single top-level element.
Any concurrent changes to either the Image or Diagram trigger a merge warning when the
second set of changes are Saved.
Caution
Polarion allows two users to concurrently open the same Diagram for editing, but it does
not attempt to merge changes. The second user who concurrently opens the diagram for editing
receives a message about who is editing the diagram, for how long, and warning that changes are
not merged.
A Work Item Description with multiple elements: Concurrent changes to any of the elements within
the Description, trigger a merge warning when the second set of changes are Saved.
(Polarion doesn't differentiate between different top-level elements in a Work Item Description.)
The following warning appears when the second set of changes is Saved for any of the top-level
concurrent change scenarios described above:
Click both Changes done by others and Your unsaved changes before you click Save.
Procedure
1. Click Changes done by others to launch a new browser tab that highlights the changes saved by the
other user while you were working.
(Click on the top right to cycle through multiple changes. See Compare Document revisions
for more information.)
2. Click your changes since last save to launch a new browser tab that highlights the changes you
made.
3. Click Cancel on the warning dialog and refresh the browser tab.
(This will refresh the Document with the saved changes made by the other user.)
4. Switch back to the browser tab that contains your changes, paste them into the updated
Document and click Save.
• Coordinate and communicate about collaboration, and avoid having users change the same top-level
elements of the same Document at the same time. Instant messaging apps can help with this.
(For example, User 1 works with one chapter or section, and User 2 with another. )
• Get in the habit of refreshing a Document right before you dive into making changes.
• Save changes often. This reduces the chances of a conflict, and if one does occur, there will be less
content to synchronize manually.
• Make use of Collaboration Notifications.
(Ask your administrator to enable them if you don't see them on the toolbar.)
Tip
See Merge concurrent changes to view examples of merge and conflict scenarios.
The Round-trip for Microsoft Word (Word Round-trip) feature enables you to export any Document
to Microsoft Word format and share it with people who do not have access to your Polarion portal. It can
also enable a Document author to work on the Document off-line. The exported document, along with all
changes to the content, can then be imported back to Polarion, where the changes are incorporated into
the Document in Polarion, and the Document History is updated.
When exporting the Document, you can control the level of change that people can make to the exported
document.
Tip
You can also send Documents to Teamcenter Share and update them with changes done there.
• Export for Review: Content cannot be changed. Comments can be added to Work Items or text. On
reimport, the comments are incorporated into the Document in the Polarion portal.
After reimport to Polarion, comments associated with text that is not part of a Work Item appear as
usual in the Document. Comments associated with content marked as Work Items appear as comments
in the Document only. That is, they do not appear in other views of Work Items — in the Comments
section of the Work Item in the Table view of the integrated Tracker, for example.
• Export for Prioritization: Change is restricted to simple, single-value Work Item data fields such
as Severity. Allowed fields are specified by the person exporting the Document. The user of the
exported round-trip document can also insert comments to Work Item Descriptions and to text that is
not part of a Work Item. When the round-trip document is reimported to Polarion after changes, the
Document's Work Items are updated with any changes made in the exported document, and the Work
Item's History is updated.
• Export for Collaboration: Enables the user of the exported document to change the text in the
document as well as the Description and/or Severity level of Work Items, and multiline text
and rich text fields. The document user can also insert comments to Work Item descriptions and to
text that is not part of a Work Item, or remove existing comments. This export option can also be
used by authors who want to work on a Document offline. In the exported round-trip document, Work
Items can only be modified, not created, copied, or deleted. When a changed round-trip document
is re-imported into Polarion, the original Document is updated with all changes to text content,
comments, and Work Items, and the relevant histories are updated.
Tip
You can prevent pages breaks from occurring within Work Items by enabling the No Page Break option
in the Work Item Presentation dialog box, accessible in The Document Editor when you click the Work
Item type icon in the toolbar. When selected for any Work Item type, Polarion attempts, as much as
possible, not to have page breaks occur in Work Items in the exported Microsoft Word document.
Warning
• If the Document contained comments when it was exported, and the user of the exported round-trip
document changes the text of existing comments, these changes are not imported back to Polarion.
Round-trip document users should add new comments.
• If the default paragraph style of a Microsoft Word document is customized, it will not affect its
appearance when imported into Polarion, but will be applied when exported back into Word.
• HTML and CSS styles inserted into a Wiki content block may not export correctly. To ensure that
styles are exported as expected, only use the styles that are created by Polarion's Document Editor.
• Polarion does not clean up HTML within a Wiki content block. If a block contains invalid HTML, even
though it may look fine in a browser, it may look different when exported to PDF or Word formats.
Recommendation: Use something like HTML TIDY to clean up Wiki content block HTML before
exporting.
• Cross-references created in Polarion will survive a Word Round-trip, but instead of scrolling in the
Word document, they will open the referenced object in Polarion. Cross-references created in Word
will not be recognized when imported into Polarion.
• Known issue when exporting to a Word document:
◦ Custom field values exported to a Word document add additional unwanted values.
◦ Workaround: Double-check the exported document and remove any unwanted data.
See Macros and Wiki mark-up support in Word Round-trip for more information.
Note
Organizations can optionally implement restrictions via the plugin API to influence the template used for
export to Microsoft Word and Excel, with restrictions on individual exports by individual users, to include
a watermark in the exported documents and/or to conform to other required policies. If such a plugin is
in use, the Round-trip: Export Document dialog box shows a message: The selected template may be
substituted with one that complies with company policy.
Tip
Embedded image or attachment previews are preserved during the Word Round-trip process.
Procedure
1. Open the Document in the Document Editor. (Click it when browsing Documents and Pages in
Navigation or in search results.)
2. In the Document Editor toolbar, click and choose Word Round-trip Export Document. The
Round-trip: Export Document dialog box appears.
3. In the Round-trip: Export Document dialog box, select Review.
4. If you want to exclude comments currently in the Document from the export, select the Export
without comments check box.
5. Click Start. When prompted, choose a location to store the exported document and click OK.
You can import and export Polarion Live Documents to and from Teamcenter Share.
Note
• This feature requires a Hybrid-SaaS subscription license.
• You must configure this feature before you can use it.
• View the current limitations.
The new Teamcenter Share cloud collaboration tool lets you share Documents (as word documents)
from Polarion with partners, team members, and manufacturers, from anywhere, at any time to support
ad-hoc collaboration. Changes from these stakeholders can then be round-tripped back into Polarion. The
optional Teamcenter Share connector can also be used to synchronize Teamcenter Share Cloud content
with your local file system.
Note
Because the Polarion/Teamcenter Share integration uses Polarion Word round-trip, you should become
familiar with its capabilities first before using Teamcenter Share.
Once configured, you can access Teamcenter Share from within Polarion or from https://
share.sws.siemens.com/.
Current Capabilities:
When you export a Document to Teamcenter Share, Polarion converts it to a Microsoft Word (.docx)
document.
When you Import changes made in the Teamcenter Share version, the Word document is converted back
into a Polarion Live Document.
Procedure
Click on the top right, select Document Properties and click beside the Teamcenter Share
project that you want to export to. Then skip to step 4.
Click on in the toolbar, select Word Round-trip then Send to Teamcenter Share.
3. Polarion launches a new browser tab where you must sign in with your Siemens account.
4. Select the Teamcenter Share project you want to send the Document to in the drop-down menu.
(If you clicked on the Document's Properties sidebar, the Teamcenter Share project is
preselected.)
6. Click Send.
The Document is converted to a Microsoft Word document and sent to Teamcenter Share.
Once complete, the Send to Teamcenter Share dialog box appears confirming the transfer.
• Import Word document updates from Teamcenter Share. (Round-trip from Teamcenter Share.)
(Preselects the Teamcenter Share project and Word document.)
Every time you export, import or delete a Document to or from Teamcenter Share, a new revision is
created in the Document's History.
When you import a Polarion document from Teamcenter Share, Polarion converts it from a Word document
(.docx) back to a Polarion Document.
Procedure
2. There are two ways you can import Document updates from Teamcenter Share:
• Click on the top right, select Document Properties and click beside the Teamcenter Share
project that you want to import changes from.
(You can then skip right to Step 7.)
Note
If you've already logged into Teamcenter Share from your browser account, everything loads in the
same browser tab.
5. When Polarion successfully connects to Teamcenter Share, the following dialog box appears in the
newly launched tab.
Current Limitations
• Teamcenter Share round-trip from Polarion is currently not available for Historical revisions or
Baselined Documents.
• Currently, Polarion always stores exported Word documents in the root folder of the Teamcenter Share
project.
All you need is an Teamcenter Share account and you can logon to https://share.sws.siemens.com/ from
anywhere to collaborate on Polarion Live Documents.
Teamcenter Share is very intuitive, but you can click on the bottom left to access its walkthrough help.
It makes it easy to create and share content.
When you export a Document to Microsoft Word using the Export for Prioritization option, changes to
the exported document are limited to selected Work Item data fields and comments. The Description field
of Work Items is always read-only in the exported file.
Procedure
1. Open the Document in the Document Editor. (Click it when browsing Documents and Pages
in Navigation or in search results.)
2. In the Document Editor toolbar, click select Word Round-trip Export Document. The
Round-trip: Export Document dialog box appears.
3. In the Round-trip: Export Document dialog box, select Prioritization. A table of Work Item data
fields appears in the dialog box listing the fields you may allow users of the exported document to
change.
4. Select the check boxes next to the names of Work Item fields you wish to allow users of the exported
document to change.
5. If you want to exclude comments currently in the Document from the export, select the Export
without comments check box.
6. If you want your current selections to be the default for all subsequent exports, select the Remember
this configuration check box.
7. Click Start.
Procedure
1. Open the Document in the Document Editor. (Click it when browsing Documents and Pages
in Navigation or in search results.)
2. In the Document Editor toolbar, click and choose Word Round-trip Export Document.
The Round-trip: Export Document dialog box appears.
3. In the Round-trip: Export Document dialog box, select Collaboration. A table of Work Item data
fields appears in the dialog box listing the fields you may allow users of the exported document to
change.
A Page Breakin Polarion sets the orientation of the section above it.
Import Documents
In Microsoft Word, you can create sections and define features, like orientation, for them. Page orientation
is handled by Page Breaks in Polarion.
When you import documents with landscape-orientated pages, Polarion. will add a landscape Page Break
( ) after every landscape-oriented section.
Export Documents
You can create new Page Breaks or just use those that were imported. If you change their orientation,
they will set the orientation for the sections/pages above them. When exporting to Word, Polarion creates
new sections if it detects page orientation changes. Otherwise, it inserts normal page breaks in the
Document.
The page size of these sections is taken from the last section in the body of the imported document or is
set to the default size.
The Page Break at the end of a Document defines the orientation of the last section of the Document.
If you insert a Page Break at the end of a Document, an extra space appears where you can type.
If you do not remove this extra space, there will be an extra portrait-oriented page at the end of the
Document.
The default orientation for Documents is portrait. If you import a document ending with a landscape
section, you will see an extra Page Break at the end of the Document. This final Page Break does not
create an extra page in PDF or Word Export.
See Insert Page Breaks for more information on how to use them.
Only the headers and footers from the first section are used for the whole Document. If you use different
headers and footers in the Document, they are lost during Word Round-trip.
You can have a different header for the first page, but it must be defined in the first section of the
Document.
Limitations
If a Document was created using the Import from Microsoft Word feature, and the original document
contained a table of contents (TOC), the properties of the original TOC are stored during the original
import, and used when the Document is exported via the Word Round-tripfeature. The TOC in the
resulting Word document has the same properties as the TOC of the original source Document, and they
cannot be changed in the exported Word document.
If the Document was created in Polarion and you added a TOC, the Word Round-trip exporter creates a
standard TOC in the exported Word document.
Make more than three Polarion headings appear in a Microsoft Word TOC
By default, when you update a TOC in Microsoft Word, only three levels of headings will appear even
though it supports up to nine levels.
If you have more than three levels of headings defined in your exported Polarion Document, you must do
the following for them to appear in Word.
Procedure
4. Replace the 3 with the number of headings that you want to appear (to a maximum of 9) and press
ALT +F9 again.
5. Click Update Table, select Update entire table and click OK.
The additional heading levels you added in Polarion now appear in the Word document.
When you create a new Document via import from Word, Polarion creates a Microsoft Word template
file named roundtrip.docx based on the styles in the original Word document. If you later export the
Document from Polarion using Word Round-trip Export, the content of the Document in Polarion will be
formatted according to the template that was stored during the initial import.
Polarion comes with a global default export template that defines header, footer, and basic styles. The
template is used to format Word documents created from Polarion LiveDoc Documents using Word Round-
trip Export. You can optionally create a copy of this template to use with specific projects.
You can customize any export template to define the styling of the exported Round-trip document as
described later in this topic. For information on accessing round-trip export templates, see Round-trip
Export Template Locations.
A Word Round-trip template can define styles for all the heading levels using paragraphs with text Heading
N where N is the heading level number — 7, for example. All the defined styles can be used in the
round-trip Document by users to create headings. If the template does not include enough heading styles
for the exported Polarion Document, the needed styles are created by Polarion with names Heading N,
where N is the level number. Microsoft Word supports only nine heading levels, even in the numbering, so
the headings above Heading 9 level cannot have an outline number.
1. Navigate to the Administration topic Work Items Round-trip Template in the repository
or project scope, or to its location in the repository using the Repository Browser.
2. Download the roundtrip.docx to your local system.
3. Edit the roundtrip.docx file in Word to defines the styles you want, saving your changes locally.
4. Upload the edited roundtrip.docx file back to the repository in the same location you took it from,
using the relevant Administration page or the Repository Browser.
If you downloaded a template file in order to create a project-scope round-trip export template for a
project that did not already have one, upload to the project location described in Round-trip Export
Template Locations.
Note
You need read and write permissions for the repository and the templates folder. For information on
field IDs that you can include in a customized template, see Round-trip Export Template Fields.
When editing any Document, the Word Round-trip Template of the Document Properties panel of
the Document Sidebar enables you to upload a Word document to be used as the export template
for Word Round-trip exports of the current Document. Microsoft Office Word documents saved in .docx
format can be used to create a template for Word Round-trip, or you can upload a customized Word Round-
trip template previously downloaded from Polarion. When you click the Upload link in the Document
Properties panel of the Document Sidebar, the Upload Round-trip Template dialog box presents options
for each type of upload.
• The Download link is enabled in the sidebar pane which you can use to download the current
round-trip template for customization. A mouse-over tool-tip indicates which template is available for
downloading: default or custom.
• The Remove (use default) link is enabled. Clicking it removes the previously uploaded Document-
specific round-trip template. The default round-trip template for the project will then be used for any
Word Round-trip operations.
The Document Properties panel of the Document Sidebar provides access to a round-trip template file
used for round-trip operations with the Document. It may be either the global or project default template,
or a custom template uploaded by a user.
You define a header and footer as you would normally do in Word. However, you can include some
predefined variables in the header/footer in content controls, for which values are substituted in the output
during the export process:
Tip
If you need more details about these, see the reference topic Round-trip Export Template Fields.
Polarion will fill these content controls, if present, when the Document is exported with Round-trip Export.
To add one of the above variables to a header/footer, you add a plain text content control to header/footer
and set its tag to the value of the identifier.
Using the Table of Contents feature in Word, insert a table of contents into the round-trip export template
document if one is not already present, or if you want to change the style of an existing table. Set the
depth of the table of contents in the usual way in the Word version you are using.
Customize styles
The default templates contain several content elements — headings, paragraphs, and more — with some
default styles. Use the Format Styles feature of Microsoft Word to change the properties of any existing
style in the round-trip template you are customizing. Do not simply change the style of the individual
element (heading or paragraph) using commands such as Format Paragraph or Format Font.
After an exported round-trip document has been changed, it can be reimported to Polarion to synchronize
the changes with the original LiveDoc Document. Before reimporting, make sure the changed round-trip
document is in some location that is accessible when you are working in Polarion.
Procedure
1. Open the original Document in the Document Editor. That is, the document that was previously
exported using the Word Round-trip Export Document command in the Document's menu.
(Click the Document name when browsing Documents and Pages in Navigation or in search
results.)
2. In the Document Editor toolbar, click and choose Word Round-trip Import Changes. The
Round-trip: Import Changes dialog box appears.
3. In the dialog box, click Browse, navigate to and select the Word document you wish to reimport.
4. Select any of the options you want to apply to the reimport process:
• Overwrite Conflicts: If selected, then changes in the re-imported document that conflict with the
Live Document will take precedence and overwrite the same part of the Live Document. If
this option is not selected, and conflicts occur, the import will fail and no changes will be imported
to Polarion, even on-conflicting changes.
• Import Only Comments: If selected, all changes made to the exported Word document will be
ignored by the reimport process except any comments which were added. Comments will be
added to the Live Document in the same position as they appear in the Word document. No
text is replaced.
Notes on Reimporting
When an exported round-trip document is reimported to Polarion, the following points apply.
• A conflict can occur if the same Document content is changed online after a round-trip export, and
in the exported round-trip document. When the round-trip document is reimported, the conflict is
reported. Reimport can succeed only if the importing user selects the Overwrite Conflicts option during
the reimport operation.
Warning
If the overwrite option is chosen, the content in the portal is overwritten with the content of the
reimported document. The previous version of the content still exists in the Document history.
• If Document text is not changed in the round-trip document, then there is no new revision of the
underlying system data file after import. However, it still shows in Document history.
• If Work Item description or any other field is unchanged in the round-trip document, there is no change
in the field(s) in the history of the Work Item.
Document Properties
Related Topics
Documents have a set of properties which can be read and/or set in the Document Editor. A complete
history of every Document is automatically maintained. A new revision is created in the repository each
time a Document is modified and saved. Revisions can be easily compared.
Document properties appear in the Properties panel of the Document Sidebar. Open it from the toolbar
by clicking Show Sidebar Document Properties.
This topic discusses two Document properties that users often opt to adjust. You can find information
about all Document properties in the Reference topic Document Properties sidebar.
Auto-Suspect Property
If this property is enabled in the Document, the Suspect attribute is applied automatically to child
Work Item links, if the parent Work Item is modified. (This setting takes effect when you Save the
Document.) Auto-Suspect works for Document Work Items even if Auto-Suspect is not enabled in
Administration. The Suspect flag set on Work Items can be useful for change impact analysis. For
more information, see Suspect Default State and Suspect Links.
Note
The Suspect attribute is only applied to links to child Work Items. (Not to Parent or Structural links
within a Document.)
The On-demand Work Item Loading feature can dramatically increase the response time, especially when
editing Documents that contain many Work Items. When enabled, Work Items are not loaded until
they are scrolled into view rather than waiting for all Work Items to be loaded. This makes editing large
Documents more fluid and user-friendly.
On-demand Work Item Loading is enabled by default for Documents containing 200 or more Work
Items.
Administrators can set system-wide behavior in the system configuration. You can turn it ON or OFF
for any Document in the Document Sidebar. There are currently some limitations that occur when
On-demand Work Item Loading is turned ON:
• If you wish to copy some items and paste them in the same Document, make sure that all the items
have finished loading before pasting. The items are loaded if they have scrolled into view at least once.
This limitation does not apply when pasting copied Work Items to a different Document.
• Caption numbers are sometimes replaced with the hash character # while viewing the Document in
Polarion. The # hash characters are replaced with the correct numbers when the Document is exported.
See the reference topic Caption for information.
On-demand Work Item Loading can be set to ON/ OFF for a Document in the Document Properties
Sidebar of the Document Editor.
Procedure
1. Click Documents and Pages in Navigation, and select the target Document. If there are many
Documents, you can open the Space's Index page, locate the Document to edit, and open it from
there.
Polarion automatically maintains a history of each Document. Every time you save the Document a new
revision is created in the history. You can easily review any revision, and you can compare any two
revisions to understand what changes took place between the older and the newer revisions.
Note
Changes to the custom field names are not shown in the Document History.
Each revision of the Document is automatically assigned a unique numerical ID, and is stamped with the
date and time the revision was written to the repository. If you know the revision number you want to see,
you can use your browser's Find feature to locate it on the Document history page. In addition to the date
and time, the Document history page shows how long ago each revision took place.
Tip
You can also label important document changes so that they're easily identifiable in the Document's
history by creating a Document Baseline.
To view a Document's history, click clock icon the Document Editor toolbar. You can also access the
history via the View History link in the Document Properties panel of the Document Sidebar.
Tip
Select Show only baselines to hide normal revisions and only show Document and Project baselines.
(This setting is remembered for the current user across all Documents.)
You can browse the table of revisions until you find one you want to view. Then click Show in the Actions
column. The Document loads in the editor in the state it was when the revision was saved, but the content
is read-only and cannot be changed.
Note
If a Document revision is opened that contains a block of Wiki syntax, but a historical index of the
database is currently in progress, then the block’s content will not be displayed until the indexing is
complete. While the historical indexing is in progress, the following warning message appears:
Warning
Historical database indexing in progress. The Document's Wiki macros will not be rendered until it's
complete.
You can use the Current Revision button to return to the current state of the Document in the editor.
Note
Baseline revisions that do not match will have the revision number and name rendered in italics in all link
states (normal, hover, selected).
You can compare any two revisions on the Document History page. You cannot compare more than two
revisions at once.
Note
Changes to the custom field names are not shown in the Document History.
Procedure
Removed items are highlighted in , added items are highlighted in and formatting changes
are highlighted in .
Tip
You can set your view to High contrast.
When cells that contain text are merged and then compared with a previous version, the layout will appear
a little strange in the comparison view.
(This only affects the comparison view. When exporting or viewing the most recent, merged cell revision,
or the historical revision before the merge, both layouts will appear as expected.)
After comparing two revisions, you can export the comparison result to PDF. You can only export the
Document (content) view.
Procedure
3. In the Document view, click on the toolbar, and choose Export to PDF.
4. In the Export to PDF dialog, set the export options as desired and click Export.
Document outline
The Outline panel of the Document Sidebar displays a hierarchical tree of the Document's headings,
including titles of contained Work Items. The Document outline can help you browse the Document
structure to some specific part of a Document. Clicking a node scrolls the Document content to the
respective heading or Work Item. When you are editing content in the Document body, the nearest parent
heading or title is selected in the Outline panel.
If the outline is large you can enter some text in the Filter control at the top of the panel to filter the outline
for the input text. If you add or remove content in the Document, you can use the Update button to
refresh the outline tree.
For more information see the reference topic Document Outline Sidebar.
Document actions
Reuse a Document
Warning
If a reused Document contains Work Items that have been approved using an electronic signature, the
Work Items in new Documents do not show any indication of the source items' signatures, and reused
items in the new Document are not approved or electronically signed. These items must be reviewed,
approved, and e-signed.
You can reuse an existing Document, or any revision of an existing Document, including a Document
Baseline. To determine the number of a revision of a Document to reuse, review the Document history.
You can reuse Documents in the same project, in the same space or a different space, or in a different
project in any space in that project. You can either create a new, stand-alone copy of a reused Document,
or a derived copy in which the text/image content can only be modified from the base Document, but
which allows changes to some Work Item fields in the copy — the Status field, for example.
Tip
The difference between Branch, Reuse, and Branch Documents:
• When you Branch a Document you create a variant Document that you can continually compare
(and merge) with the original Master Document.
• You can Branch a filtered version of one or more Master Documents if you want to branch a subset
of Work Items within the Master Document(s).
• With Branch Documents you can Overwrite Work Items and Initialize Work Item fields
automatically.
Use Branch Documents for a single Document to automatically apply these options.
(You must manually Overwrite Work Items and Initialize Work Item fields with Branch.)
You can Reuse multiple Documents in a single operation. You can optionally keep relative links between
the Work Items contained in the reused Documents.
For example, if you reuse two specification Documents where one contains functional requirements, and
the other contains test cases linked to the functional requirements in the requirements specification, you
can have the test cases in the reused test case specification linked to the same requirements in the reused
requirements specification.
If your system or project is configured to support Document types, a reused Document is of the same
type as the original. If your system is configured to use Document workflow, the workflow on new
Documents created by reuse is set to the initial workflow status specified in the project workflow
configuration. However, the workflow for Work Items contained in the duplicated Document is not
triggered. Consequently, the initial workflow Action set in the Work Item workflow configuration is never
triggered, and therefore the InvokeAction workflow function of the original Document has no effect in
the reused Document.
Caution
Writing a custom workflow action script replacing the InvokeAction function in the reused Document is
strongly discouraged. It is risky, and in the best case, it also will not work.
Note
• Document Comments in a Document you Reuse will not be included in the new Document.
(Document Comments should not be confused with Work Item Comments. They behave
differently.)
• Administrators can configure Quick Create so users can reuse a Document right from the
Navigation Header.
Reuse a Document
You can reuse an existing Document, or any revision of an existing Document, or Document Baseline.
Tip
What's the difference between Reuse and Branch?
Procedure
4. (Optional) If you want to reuse a revision of the Document other than the current HEAD revision,
click .
Select one of the following options in the Select Document revision dialog box:
b. Select Revision and enter the number of the Document revision you want to reuse or click
and select the revision in the Revision Picker dialog box.
5. In the Title field, optionally specify a different title for the new Document to be created as a result of
the reuse operation.
If you modify the Title field, and you want the heading styled as Title in the Document to be updated
to that value, select the check box labeled Update Title (Heading) in the Document. Clear the box if
you want the original title preserved in the new Document.
6. In the Name (ID) field, optionally specify a different name for the new Document to be created as
a result of the reuse operation. If this Document is saved in the same space as the base Document,
you must specify a new name to avoid a conflict with the name of the base Document.
7. By default, the new Document is saved in the same project as the base Document. If you want to
save it in a different project, select the target project in the Project list.
8. By default, the new Document is saved in the Default space of the project selected in Project. If you
want to save it to a different space, select the space name in the Space list.
9. (Optional) Select the Remove outgoing Work Item links check box. When selected, links from Work
Items contained in the base Document to other Work Items in the project, or another project, are
not created in the duplicated Work Items in the new Document. You might want to do this if the
base Document is a production Document, as opposed to being some kind of library document, or a
template for production Documents.
Tip
See Remove outgoing Work Item links for details on what links are removed and preserved.
• To create a new, stand-alone, fully editable copy of the base Document, select Create a new
stand-alone copy of the Document.
If you select this option, also specify whether or not to link the duplicate Document's Work Items
to the base Document's Work Items. If you opt to link, select the link role in the drop-down list.
• To create a copy of the base Document which cannot be edited (except for some Work Item
field values), select Create a new derived Document. (For more information, see Derived
Documents.)
If you select this option, specify which Work Item fields should be read-only in the derived
duplicate. By default, the Title and Description fields are specified. You may optionally add other
fields, delimiting the list with a comma. For example, if you want the Severity field to be read-only
in the Derived Document, add it to the Derived Fields field.
11. Click OK to create the new Document copy in the specified project and space.
Results
The new copy opens in the Document Editor and is selected in Navigation. If the new copy was saved to a
different project from the base Document, that project is opened before opening the Document.
Derived Documents
Reusing a Document with the option to create a new Derived Document lets you use the first Document
as a standard. For example, if you have a standard set of requirements or specifications that must be
implemented in every project, you can create one base Document — from which other Documents are
derived, and reuse it in projects as a Derived Document. A Derived Document is an exact copy of the
base Document, which cannot be modified other than to set values of some Work Item fields — Status or
Severity, for example — if these were not configured as read-only when the base Document was reused.
Work Items contained in the base Document are duplicated in the project containing a new Derived
Document, and assigned new IDs. These items can then be tracked and managed as Work Items in the
project containing the Derived Document, which may be different from that of the base Document.
The advantage of Derived Document is that if something changes in the base Document — a new
requirement is added, for example — the change can be easily propagated to all Derived Document,
resulting in the creation of new Work Items, and sending of notifications about them to the Document
owner.
Tip
There are several important things to keep in mind about Derived Documents.
• If the source Document is moved or renamed, links to all Derived Documents are updated
automatically.
• If you try to remove the source Document, or the space containing it, you are warned about the
presence of Derived Documents and offered the choice of canceling the action, or converting the
Derived Documents to stand-alone Documents. If you choose to convert, the link to the source
Document is lost. Links between Work Items contained in the derived Document are preserved.
• If the project is configured to support Document types and Document workflow, updating a derived
Document from the base Document does not affect the Type or workflow Status of the Derived
Document.
• If there are any attachments (images, diagrams, or previews) referenced in a Description or Test Step
field, then they are implicitly derived with the rich-text field content even if the Attachments field itself
is not a derived field.
• For Derived Documents, you can use the Recycle Bin to view Work Items that are no longer part of
the Document but cannot Insert, Move or Delete items.
(You can delete them using the Work Item detail form or tracker views like Table or Tree.)
Note
A derived Work Item will copy Work Item comments from its master Work Item, but the Comments
field can NOT be set as derived. After the initial derive operation is complete, any additional comments
in the original Work Item won't be propagated to its derived copy during an update.
When the content of a base Document changes, the change may be propagated to any or all Derived
Document.
Caution
Changes are not propagated automatically. This gives users the option not to propagate base Document
changes to some derived Documents. The owner of the base Document should manually notify owners
of derived Documents about changes that they may want to incorporate.
Procedure
Tip
You can also update the derived Document using the Update link in the Document Properties
panel of the Document Sidebar.
You cannot create a Derived Document from a Document that contains referenced Work Items.
When updating a derived Document, there is an option to set the Suspect attribute on incoming links.
When set, then links incoming to Work Items modified by the update operation are marked as suspect.
The user updating the derived Document and setting the Suspect option must have permissions to update
the linked items, otherwise the update cannot proceed and the user receives an error message.
For example, setting links as suspect would be desirable when updating a derived requirements
specification Document that has verifying test cases linked to the contained requirements. Because the
linked test cases could be invalidated or broken by the update, flagging the links as suspect helps ensure
that owners of the test cases are made aware that changes have occurred in the requirements so that they
can review the test cases.
When you select Remove outgoing Work Item links, all links from Work Items contained in the Master
Document to other Work Items in the project, or another project, are removed from the duplicated Work
Items in the updated Document.
• If you select Remove outgoing Work Item links, all links from Work Items in the Master Document to
other Work Items (in the same or different Projects) get removed from the new Document.
• If you do not select Remove outgoing Work Item links, the new Work Items contain the same Work
Item links as the originals.
• Backlinks (like is related to) are not copied to new Work Items because the original items own
them, and they may not apply to the new Work Items.
• If Work Items are only referenced in a Reused Document, they appear as they were (referenced),
and their links are not affected by the Remove outgoing Work Item links option.
• When you Update, you can only manage the outgoing links for new Work Items propagated to
Derived Documents.
• If you edit Work Items in the Master Document (by adding/removing links), changes are not
propagated to the Derived Document when you Update.
Example
A selected Source Document has a Requirement (RQ1) Work Item with an outgoing link to a Test Case
(TC5).
• Don’t select Remove outgoing Work Item links if the copy of the Requirement (RQ2) in the new
Target Document can be tested by the same Test Case (TC5).
• If you want the new Target Document to be, for example, a specification document for a different
operating system that requires a different testing procedure, then select Remove outgoing Work
Item links because it makes no sense to link RQ2 to Test Case (TC5). (The Test Case won't be copied to
the Target Document.)
(Outgoing Work Item links will remain for Referenced Work Item copies.)
You can reuse multiple Documents in a single operation. You can optionally keep relative links between
the Work Items contained in the reused Documents.
Example
If you reuse two specification Documents where one contains functional requirements, and the other
contains test cases linked to the functional requirements in the requirements specification, you can
have the test cases in the reused test case specification linked to the same requirements in the reused
requirements specification.
Reusing multiple Documents in a single operation can be especially useful where you have a set of
standard or boilerplate Documents that need to be reused in multiple projects. The base Documents to be
reused can reside in any Project and Space, and can be reused in any other project and space.
Procedure
1. In Navigation in the project containing the base Documents to be reused, navigate to the
Space containing the base Documents and select Index.
The Index page opens listing all Documents in the Space.
2. Select each Document you want to reuse and click Reuse Documents in the toolbar at the top.
4. (Optional) Select any additional Documents you want to reuse. Initially the table of selected
Documents contains only the Documents you selected on the Index, which means they
are from the current Project and Space.
• You can add Documents from any Project, and from any Space in a specified project. Use
the icon to add a new row for each Document you want to reuse, specifying the Project and
Space in the selected project, and Document in the selected Space.
• If you make a mistake, use the minus icon to remove the incorrect Document's row in the table.
• By default, the HEAD revision of each selected Document in the table is the revision reused.
If you want to reuse a different revision of any Document, click HEAD on the relevant table row
and specify the number of the revision you want to reuse.
5. Click Next.
The next steps depend on whether or not you selected the option Use same project and settings for
all reused Documents (it is selected by default).
6. If you selected Use same project and settings for all reused Documents:
a. In the Project list, select the Project where you want to put the reused Document(s). The
current Project is the default.
b. Provide a Name and Title for each Document, and specify the Space in the target Project
where each reused Document should be created.
Note
Each Document's name is the identifier (ID) for the system, so it must be unique within the
target Space.
You can see a Settings item for each of the base Documents you selected for reuse where you can
specify different target locations and custom reuse options.
On the Settings page for each base Document:
a. Specify the target Project you want the reused Document to be placed in. The current project is
the default.
b. Provide a Name and Title for the Document, and specify the Space in the target project where
the reused Document should be created.
Note
Each Document's name is the identifier (ID) for the system, so it must be unique within the
target Space.
9. When you have opened the Documents you want, click Finish to close the wizard window.
Combine Documents
Combine lets you merge multiple Documents into a new standalone Document. You can drag
and drop the order that you'd like the combined Documents to appear, select Documents from
more than one Project and chose a Master Document that you want the combined document to
inherit Document Properties like Outline number settings and more from.
Tip
Looking to add one or more Documents to an existing Document? You should Append them.
Caution
If two or more Documents have the same image file with identical names (in the body not within Work
Items), the Combine process will report an error. To avoid this, just rename one of the images or insert
them in the Description of a Work Item.
• Document Combine works as a Job and its progress can be checked in the Monitor topic.
• Relative links between Work Items within selected Source Documents (as well as those in the
Master), are always kept.
(But if a Relative link in a Source Document is the same as the structural link role of the Master
Document, then it will be deleted.)
• Because a Document can only contain a single copy of any given Referenced Work Item, if it is
referenced more than once in the Documents you are combining, the first one found will remain as a
Referenced Work Item and the rest will be converted to standalone copies of the original Work Item.
◦ Any changes that are made to these Work Items will not be propagated to the original, and changes
to the original will only be propagated to the single Referenced Work Item in the combined
Document.
◦ The status, signatures and approval states of Work Item copies will not change if they're updated
in the original.
◦ Outgoing links for Referenced Work Item copies will always be preserved, even if the Remove
outgoing Work Item links box is selected.
(Each copy will have a branched from link.)
• You create a new Title for the combined Document, but the Titles from the combined Source
Documents are also preserved and included in the new Document.
• A combined Document is set to the initial workflow state determined by your configured workflow.
• You can select a Source Document from a Project Baseline , but you can't combine Documents
when you are in Project Baseline view.
To Combine Documents
Procedure
Tip
Looking to combine Documents from other Spaces or Projects? You can select them in
Step 4.
Note
If you only select a single Source Document, Polarion assumes that you want to Append it to
an existing Document.
(Optional) You can also just click Combine/Append Documents and select them from the
Combine Documents dialog that follows. (See Step 4.)
• Documents are listed in the Combine Documents dialog box in the order that you select them
here.
(You can still drag and drop them where you want them in Step 5.)
• While, Reports and Classic Wiki Pages appear in the list and are selectable, they cannot be
combined into a Document.
(They don't appear in the Combine Documents dialog box if selected.)
• Documents within a Sub-Space aren't added if you select the Sub-Space from the
Index.
(They can be added in Step 4.)
4. (Optional) Select another Project or Space from their drop-down lists to add Documents from
other Projects, Spaces or Sub-Spaces.
The Document drop-down list is populated with Documents from your selected Project and
Space.
5. Select a Document in the list, hold down the left mouse button and drag it to where you want it
to appear in the Document.
(Repeat this process until you have the order you want for your Document.)
• Select Head: Stick with the most recent version of the Document.
• Select Baseline then choose a Document or Project baseline from the drop-down list.
• Revision: Enter the Revision # if you know it, or click Document History to view the available
revisions in a new browser tab .
(If you enter an invalid Revision number, a warning icon appears and OK is disabled.)
Once you've selected the version that you want, click OK.
The selected version appears in the list instead of HEAD.
7. Leave New Document checked under Target Document to combine the Source Documents.
(If you select Existing Document you will Append the selected Source Documents to an existing
Document.)
10. Select the Project that you want the combined Document to belong to.
11. Select the Space (or space_name / sub-space_name) within the Project that the
Document should reside in.
By default, the top Source document is chosen as a the Master Document and the possible
document list is updated whenever the Source document list is.
(If the selected document is removed from the Source document list the Document that takes its
place at the top of the list becomes the new Master Document.)
By default, Combine keeps all Work Item Types that are in use in the Source Documents.
Select this to also retain those that are not being used.
(See Work item Presentations for information.)
15. (Optional) Clear Link each duplicated Work Item to original with the relationship. (Selected by
default.)
(Available link roles will vary depending on the selected Source Documents and their configured
Work Item Types.)
You can either:
a. Clear this option so that duplicated Work Items are not linked to the original.
b. Keep it selected and choose a relationship other than the default.
16. Click Combine.
The document combine process begins.
Click Show log to view the log details, then click Close.
Append Documents
You can Append one or more Documents to an existing Polarion Document. (They can even be
selected from more than one Project.)
Unlike Combine, Append doesn't create a new Document but copies your selected Source
Documents to an Existing Document of your choice.
Tip
Looking to combine multiple Documents into a new Document? You should Combine them.
Caution
If two or more Documents have the same image file with identical names (in the body not within Work
Items), the Append process will report an error. To avoid this, just rename one of the images or insert
them in the Description of a Work Item.
• Append works as a Job and its progress can be checked in the Monitor topic.
• Relative links between Work Items within selected Source Documents (as well as those in the
Document you're appending them to), are always kept.
(But if a Relative link in a Source Document is the same as the structural link role of the Document
you're appending it to, then it will be deleted.)
• You cannot select a Derived Document (created via Reuse) as the Document you're appending
to because they can only be edited by updating their parent Document.
• Because a Document can only contain a single copy of any given Referenced Work Item, if it is
referenced more than once in the Documents you are combining, the first one found will remain as a
Referenced Work Item and the rest will be converted to standalone copies of the original Work Item.
◦ Any changes that are made to these Work Items will not be propagated to the original, and changes
to the original will only be propagated to the single Referenced Work Item in the combined
Document.
◦ If the Document that you're appending to contains the original Work Item referenced in any of the
Source Documents, the Referenced Work Item in the Source Document will be converted to a
standalone copy. (A single Document cannot contain both an original and a reference copy of the
same Work Item.)
◦ The status, signatures and approval states of Work Item copies will not change if they're updated
in the original.
◦ Outgoing links for Referenced Work Item copies will always be preserved, even if the Remove
outgoing Work Item links box is selected.
(Each copy will have a branched from link.)
• When you Append Documents, the Title, Name and Location are all taken from the
Document you select in the Document field.
• The updated Document will retain the workflow state it had before you appended the selected
Source Documents to it.
• Document Comments will remain in the Document you're appending to, but will not be copied
from the Source Documents.
(Document Comments should not be confused with Work Item Comments. They behave differently.)
• You can select a Source Document from a Project Baseline , but you can't append Documents
when you are in Project Baseline view.
• Word round-trip template and PDF export settings remain unchanged.
To Append Documents
Procedure
Tip
Looking to append Documents from other Spaces or Projects? You can select them in
Step 4.
Tip
If you select more than one Document, Polarion assumes that you want to Combine them in a
new Document. You can change that in Step 3.
(Optional) You can also just click Combine/Append Documents and select them from the Append
Documents dialog that follows. (See Step 4.)
• Documents are listed in the Append Documents dialog box in the order that you select them
here.
(You can still drag and drop them where you want them in Step 5.)
• While, Reports and Classic Wiki Pages appear in the list and are selectable, they cannot be
appended to a Document.
(They don't appear in the Append Documents dialog box if selected.)
• Documents within a Sub-Space aren't added if you select the Sub-Space from the
Index.
4. (Optional) Select another Project or Space from their drop-down lists to add Documents from
other Projects, Spaces or Sub-Spaces .
The Document drop-down list will be populated with Documents from your selected Project
and Space.
5. Select a Document in the list, hold down the left mouse button and drag it to where you want it
to appear in the Document.
(Repeat this process until you have the order you want for your Document.)
• Select Head: Stick with the most recent version of the Document.
• Select Baseline then choose a Document or Project baseline from the drop-down list.
• Revision: Enter the Revision # if you know it or click Document History to view the available
revisions in a new browser tab.
(If you enter an invalid Revision number, a warning icon appears and OK is disabled.)
Once you've selected the version that you want, click OK.
The selected version appears in the list instead of HEAD.
(If you leave New Document selected will Combine the selected Source Documents into a new
Document.)
8. Select the Project that contains the Document that you want to append your selected Source
Documents to.
9. Select the Space that contains the Document that you want to append your selected Source
Documents to.
10. Select the Document that you want to append your selected Source Documents to.
Document Properties (like outline numbering) are taken from this Document.
By default, Append keeps all Work Item Types (including those that are unused) defined in the
Document you're appending to, but only preserves Source Document Work Item Types that are
being used.
Select this to retain the unused Work Item Types that are defined in all of the selected Source
Documents.
(See Work item Presentations for information.)
13. (Optional) Clear Link each duplicated Work Item to original with the relationship. (Selected by
default.)
(Available link roles will vary depending on the selected Source Documents and their configured
Work Item Types.)
You can either:
a. Clear this option so that duplicated Work Items are not linked to the original.
b. Keep it selected and choose a relationship other than the default.
14. Click Append.
The document append process begins.
Click Show log to view the log details, then click Close.
You can move a Live Doc to a different Space or Subspace (and rename it while you do) or rename a
Document in the same Space. You can only move Documents within the current project, and the target
Space must already exist in order to move a Document to it. (Create the new Space before moving the
Document.)
Procedure
1. Open the project to which the Document belongs, if the project is not already open.
2. In Navigation, expand Documents and Pages and browse to the Space or Subspace containing
the Document and select Index in that Space.
If you are not sure where the Document is, you can filter Navigation or use the Search feature to
locate the Document and determine the Space where it resides.
3. On the Index page, locate the Document you want to move or rename, and select the check box on
its row in the table.
4. In the page toolbar, click Move/Rename Document. The Move or Rename Document dialog box
appears.
The Space hierarchy, if you've already created one, appears in the drop-down menu as follows:
Tip
Displaying of Document compare before and after moving may take a long time. The Document before
renaming is not cached and the entire history is loaded from the repository.
The Rename action is also available in the Document Properties panel of the Document Sidebar.
Delete a Document
You can delete a Document from the Index page of the Space that it resides in.
Warning
When you delete a Document, all Work Items contained within it are also deleted.
Procedure
1. Expand the Space in Navigation where your Document is and click Index.
The list of Documents and Pages contained in the Space appears.
2. Select the Document that you want to delete.
Branch a Document
Tip
The difference between Branch, Reuse, and Branch Documents:
• When you Branch a Document you create a variant Document that you can continually compare
(and merge) with the original Master Document.
• You can Branch a filtered version of one or more Master Documents if you want to branch a subset
of Work Items within the Master Document(s).
• With Branch Documents you can Overwrite Work Items or Initialize Work Item fields
automatically.
Use Branch Documents for a single Document to automatically apply these options.
(You must manually Overwrite Work Items and Initialize Work Item fields with Branch.)
Much of the original specification is applicable to all the variants — rules of the game, for example.
However, the user interactions are different for each mobile platform, so you need some way to specify
platform-specific requirements while keeping those that a applicable to all platforms but the scenario
doesn't end there. Some of the user interactions are the same across all devices running Mobile Platform A,
but there must be additional requirements for one or more specific supported devices running Platform A.
In this scenario, the requirements specification Document for desktop platforms is branched to create
variant specifications for two supported mobile platforms — Platform A and Platform B. In each of
the branched variants, some requirements from the master — that is, the original Document — are
referenced, which means that they appear in the variant, but are not contained in it, and may not be
modified in it. In the Platform B specification, one requirement from the master is removed from the
variant and replaced by a new platform-specific requirement. Then, new native Work Items — that is,
items created in the branched Documents — are added to the branched specification Documents to
address requirements specific to each platform. The native items are of the User Story type because the
mobile development uses the Scrum methodology.
At this stage the specification Documents are Desktop Requirements Specification (master Document),
Mobile Platform A Requirements Specification, and Mobile Platform B Requirements Specification. If Work
Items in the master Document are modified, the changes propagate to the variant Documents. In cases
where this is not wanted, or is not wanted until some future time, the variant Documents can be frozen
to a specific Revision of the master Document, meaning that subsequent revisions of the master's Work
Items do not propagate to variants until such time as the variants are unfrozen, which means the branch
is then live, and all subsequent modifications of the master Document's Work Items will propagate to
variants.
Now, the device variants on Platform A need to be addressed. The new native requirements from the
Platform A specification are valid for Device 1, but there are some additional ones required to support
the device. The approach here is to create a new Document, and then copy all applicable content from
Mobile Platform A Requirements Specification and paste that content into it. Any headings and plain text
are copied verbatim and changes in the Platform A are not propagated. Copied and pasted Work Items are
referenced Work Items — they appear in the Device 1 specification Document, but are not contained in it.
Referenced Work Items can only be modified in the Document in which they are native — in this case the
Platform A specification.
If the project of the original Document(s) is configured to support Document Types and Document
Workflow:
• The Document Type of any branched Document is the same as that of the original Document from
which it was branched.
• The workflow is reset for every branched Document. Its status is set to the initial status specified in the
project workflow configuration, and any initial workflow action specified in the workflow configuration
runs.
There may be situations when a variant needs to be based on a specific historical revision (not depicted
in the previous figure). For example, suppose requirements for Device 2 need to be based on the Platform
A specification as it was at the time of Release 4. Assuming the a project Baseline was created at the
time of this release, you could open the project Baseline, browse to the Platform A specification, copy
content from the baseline Document, and paste into the variant Document (opened in another browser
instance). Alternatively, you could open the Baseline revision of the Document in History and use the
Branch Document feature in the Document Editor.
In the variant Document (Device 1), any of the referenced Work Items can be frozen to a specific
revision of the Work Item. If the items are subsequently updated in the source Document (Platform A
specification), the changes do not propagate to the branched Work Items in the variant Document until
such time as the Work Items in the variant are explicitly unfrozen by a user. Freezing referenced Work
Items to a revision would generally not be needed when the source of the items is a historical revision of a
Document, because the source Document revision cannot be modified.
In order to branch a Document, you must have permissions for creating new Documents and new Work
Items in the project where the branched Document is to be created. You can branch the current state of
the Document, or the state from a Baseline or other historical revision of the Document.
This section describes how to branch the current state of a Document, which is the Head revision in the
repository.
Procedure
1. Locate the Document you want to branch and open it for editing.
2. On the toolbar of the Document Editor, click Actions and choose Branch in the drop-down
menu. The Branch Document dialog box opens.
Procedure
1. Open the Document to be branched, and click History to open the Document's history.
A list of historical revisions appears.
Procedure
1. Open the Document to be branched, and click the History icon to open the Document's history.
2. On the toolbar of the History view, select the Show only baselines option.
3. Locate the Document Baseline you want to branch, and in the Actions column click Show to
open the baseline version of the Document in the Document Editor.
The procedure is similar to that described in the previous section on branching a historical revision.
Procedure
1. Open the Project Baseline containing the captured the state of the Document that you want to
create a branched Document from.
2. Click History on the Document Editor toolbar to open the Document's history.
4. Click Show in the Actions column of the your target Project Baseline to open the revision.
5. On the Document Editor toolbar, click Actions, choose Branch, and proceed as described in
Branch the current state.
You might want to create a branched Document that references only a subset of the Work Items in the
master. For example, you might create a branched Document containing only items having severity Must
Have and status Accepted.
To create such a branched Document, you must first filter the master document so that it shows only the
Work Items you want referenced in the branched Document. With the master Document open in the
editor, click the Actions and choose Filter. Enter a query that filters the Document's Work Items. For
example, status:accepted AND severity:must_have.
When the Document is filtered as you want it, proceed to branch it the same way as an unfiltered
Document.
Tip
If you use Branch Documents you can Filter one or more Documents as part of the branching
process.
Once you have some branched Documents, there are various things you may need to do with them.
You access and open branched Documents just like any other Document. You can browse spaces in
Navigation, browse the Index page of any space, or search for the Document.
You can easily compare any two Documents. A common use case is comparing a branched Document
with the master Document (that is, the original Document). You can compare the full content, Work
Items, or Work Item fields in different compare views.
Procedure
1. Open a Document that you want to compare another Document to in the Document Editor. If you
want to compare a branched Document to the master, open the branched Document.
2. Click on the Document Editor toolbar and choose one of the following:
Caution
Changes saved by another user after you've loaded a Document will not be detected.
3. (Optional) Click to select a different Revision (or the baseline revision number to select a
Document or Project Baseline), that you want to compare your Document with.
The Select Document revision dialog box appears.
b. (Option B.) Select Revision and enter a revision number or click to launch the Revision
Picker and select one.
4. (Optional) Enter a Document name in the Filter field to narrow down selection results.
5. Click OK.
The Document appears in the Document Compare view with highlighted changes.
There are three compare views that compare different content of the two Documents. Change the view by
clicking the respective buttons on the compare page toolbar.
• Document: Displays a comparison of the text content of the Documents, including the text of headings
and Work Items. This view is opened by default when you compare Documents.
• Work Items: Displays a comparison of the Documents' Work Items and their structure. The Merge side
bar is available enabling you to merge Work Items and/or fields between the compared Documents.
(For more information, see Merge Document Work Items.)
Note that some fields are not displayed in the Work Items compare view even if there have been
changes to those fields:
◦ Author
◦ Comments
◦ Created
◦ Module
• Fields: Displays a comparison of the Document's fields, for example, Title, Name, and Branched From.
The topic Branching a Filtered Document describes how a Document may be branched from a filtered
state, so that the branched Document only references the Work Items shown by the filter. If you want
to compare the branched Document to the master, you need to specify the same filter query in the Filter
field of the Compare Document dialog box.
In the previous example of filtering the master Document before branching so that it shows only
items with status Accepted and severity Must Have, the filter query was status:accepted AND
severity:must_have. In order to compare the branched Document with only the same Work Items in
the master, you would use this same query string in the Filter field of the dialog box.
You can export the Document comparison to PDF using the Export to PDF item on the Operation menu
in the comparison results page. Only the Document comparison view can be exported, not the Work
Items comparison view.
An administrator can optionally configure a header/footer for exporting the comparison view. See PDF
Export Header/Footer Properties.
On the Document Editor toolbar, the operation Compare With Last Saved Version is available. This
compares the current state of the Document with the version that you opened in the Document Editor, or
to the last saved version if the Document was saved after that.
It is possible to have several (even many) Documents that reference a Work Item. For example, there
might be a core set of requirements for a product that has 25 different models. There might be 25
branched Documents each containing the specifications for one model, and each Document referencing
the core requirements. Suppose you are looking at one specific referenced requirement, and you want to
know what other Documents reference it.
Procedure
1. If you are looking at the referenced Work Item in a branched Document, open it in the Tracker. Click
the type icon by the left border and choose Open Item on the menu.
2. On referenced Work Item's tracker page, the Open in Document button on the toolbar displays an
arrow symbol. Click the arrow to see a menu listing all the Documents that reference the Work Item.
When you create a branched Document, the Work Items you see visually are not actually contained in
the Document, but are referenced from the master Document. This is visually rendered in the Document
Editor by means of a dotted gray left border on the Work Items. Referenced Work Items cannot be edited
in the branched Document. If referenced Work Items are exported for Word or Excel round-trip from a
branched Document, they cannot be edited in the exported Word or Excel file.
You can comment referenced Work Items in a branched Document in the same way you add comments
to regular Documents (including users of Polarion Reviewer ).
With an appropriate product license, referenced Work Items in a branched Document can be commented
externally via round-trip for Microsoft Word or Microsoft Excel.
Note
Document Comments in the original Document will not propagate to the branched Document.
In a branched Document, you can branch referenced Work Items to create a Document-local copy of the
items using Overwrite. Branched Work Items are contained in the branched Document and no longer
referenced from the master Document. Rather, the local copy of each item is linked to the original item
in the master Document so that traceability is maintained. If the original item subsequently changes in
the master Document, the change does not propagate to the copy in the branched Document. Likewise,
changes to the branched Work Item have no effect on the original.
When branching a referenced Work Item, you can create the branched, Document-local copy either from
the current (Head) revision of the item, or from any revision of the item in its History.
When overwriting, the modified Work Item uses the original Work Item as a template, but does not copy
the values of workflow fields like those listed below:
• Approvals
• Author
• Created
• Comments
The fields above can be modified before the newly created Work Item is saved.
(Except Author and Created. They are populated with the user that did the overwrite and the time and
date it was done.)
Procedure
1. Open the branched Document containing the referenced Work Item to overwrite.
2. Highlight a single referenced Work Item.
3. Click the Work Item icon on the left, and then Overwrite in the menu that appears.
( then Work Item Properties to launch the Work Item Properties sidebar.)
Note
The maximum number of Work Items that can be overwritten at one time is 200.
Procedure
1. Open the branched Document containing the referenced Work Items to overwrite.
2. Highlight the multiple referenced Work Items to overwrite.
3. Open the Work Item Properties sidebar. (Click then Work Item Properties)
Tip
If you want to branch a specific revision of a referenced Work Item, you must first freeze it at the revision
you want to branch (see next section) and then perform the above steps on the item.
Warning
Overwrite a Referenced Work Item with Restrictions:
When overwriting a Work Item in a generated Variant specification Document, the restriction editor
loads the Feature Model from the master project. That is the master specification from which the
You may decide you want to prevent updating of one or more referenced Work Items in a branched
Document if the items change in the master Document. In that case, you can freeze any referenced Work
Item to a specific revision of the Work Item. The freeze might be only temporary — while development of
the master Document is still in progress, for example. When a Work Item is frozen, a small clock icon
appears with its title in the Work Item Properties sidebar.
You can unfreeze any referenced Work Item previously frozen to a revision. Unfreezing causes any
changes that occurred in the master Work Item to propagate to, and appear in the branched Document.
During development of the master Document, you may freeze previously frozen Work Items at a different
revisions throughout the process. Any changes in the new revision propagate to the referenced item in
the branched Document, but any changes subsequent to that revision will not propagate until you either
unfreeze the item, or freeze it at a different (and probably later) revision. You can perform the freeze,
unfreeze, and revision change operations on multiple referenced Work Items at once.
Note that freeze, unfreeze, and revision change operations affect only the branched Document in which
they are performed. Other branched Documents referencing the same Work Items are not affected. For
example, suppose Work Item WI-5 is referenced in two branched Documents: BD1 and BD2. The owner of
BD1 opens it and freezes WI-5 at Revision 152 (the current Head revision). Later, WI-5 is changed in the
master Document. The change is not reflected in BD1 because WI-5 is frozen. It is reflected in BD2 because
freezing the item in BD1 only affects that Document.
Procedure
1. With the branched Document open in the Document Editor, click anywhere on the content of the
Work Item you want to freeze.
2. Click the type icon at the left border and click Freeze on the drop-down menu. The Freeze Work Item
dialog box opens.
3. In the Freeze at Revision field, enter the revision number at which you want to freeze this Work
Item. You can click the Select Revision icon and use the Revision Picker dialog box to select a
revision number.
4. Click OK to complete the freeze operation.
5. After closing the dialog box, save the Document. You can confirm that the item is frozen at the
revision you specified by opening the Document Sidebar (if hidden) and then opening the Work
Item Properties sidebar. A small click icon appears by the title, and the icon tool-tip indicates the
revision number.
Procedure
4. After closing the dialog box, click Save to apply the changes.
Procedure
1. In the branched Document, select the Work Items you want to freeze or unfreeze.
2. Open the Document Sidebar and its Work Item Properties sidebar.
3. Click Freeze/Unfreeze.
4. In the dialog box, select the option you want to perform on all the selected referenced Work Items.
Note that if the selection contains Document-native, that is, not referenced Work Items, the
operation ignore them and process only referenced items.
5. After closing the dialog box, save the Document to apply the changes.
It is possible to insert multiple referenced Work Items into a Document in a single operation. Work Items
can be selected in the Tracker in the same way as selection for Bulk Edit, and the references copied and
inserted into a Document.
Procedure
1. Open the target Document in the Document Editor, and open the Work Items topic in a separate
browser tab.
4. In the toolbar lower half of the page, click Actions and select Copy Link and in the dialog box,
copy all selected links to your clipboard. Alternatively, you can select Copy IDs.
5. Go to your Document and place the insertion point on an empty line where you want to insert the
referenced items.
6. On the Document Editor toolbar, click the Work Item type icon (tooltip: Mark/Unmark Text as), and
on the menu select Insert Referenced Work Items.
7. In the Insert Referenced Work Items dialog box, paste the links (or IDs) from your clipboard into the
first text field, then click OK.
When you have referenced Work Items in a branched Document, you may want to find what other Work
Items are linked to them. These linked items are of course external to the branched Document. This is
easily accomplished using the Tree view:
Procedure
Tree shows a hierarchical view of the Document's structure including both referenced Work Items, and
items contained in the Document. The toolbar provides a special set of controls enabling you to show
linked or backlinked Work Items having a specified link role. You can control the depth of the search,
optionally include linked commits (revisions), and optionally filter all levels of the Document tree using the
current query. (If Filter Linked Items is not selected, the query is applied only to the first level of the tree.)
You can enable outline numbering in a branched Document just as you can with any other type. See
Using Outline Numbering.
In a branched Document, the outline numbering you see pertains only to the structure of that Document
regardless of any numbering that may be applied to referenced Work Items in the master Document. For
example, suppose that right after you branch a Document, you have an outline sequence 1.1, 1.2, 1.3,
and 1.4 in referenced items from the master Document, Now you insert a new Work Item in the branched
Document between referenced item 1.2 and referenced item 1.3. After you save the changes, your new
item will be numbered 1.3, the item that was numbered 1.4 will become numbered as 1.5, and the item
that was 1.5 will be numbered as 1.6, and so on down the Document content.
You can branch multiple Documents at once and pick specific revisions and custom settings for each.
Tip
• You can also use Branch Documents for a single Document if you want to Overwrite Work
Items or Initialize Work Item fields.
(You must do this manually when you Branch a Document from the menu.)
• What's the difference between Branch and Reuse?
Procedure
1. In Navigation expand Documents & Pages and the Space with your target
Document(s).
b. For selected Document: You can select individual Documents in the Source Documents table
on the left, select a specific Revision or customize their Settings individually on the right.
• Name (ID): If you want to create the branched Document in the same space as the
Document you are branching, you must enter a new Name (ID).
• Project: If you want to create the branched Document in a different Project, select the target
Project in the drop-down list.
• Space: If you want to create the branched Document(s) in a different Space than the one
selected in this field, select the target Space in the drop-down list.
The list contains the names of the Spaces in the Project selected in the Project field.
• Suffix: When you select For all Documents, rather than changing the Title of each new
Document manually, you append something to the end of all of their titles.
(_branched is the default.) The Suffix is applied to both the Title and Name ID fields.
• Filter: You might want to create a branched Document that references only a subset of the
Work Items in the Master Document. For example, you might create a branched Document
containing only items with a Must Have Severity and an Accepted Status. Just enter a query
like the following in the Filter field:
Example
status:accepted AND severity:must_have
Hover over the icon in the Document Properties sidebar to see what Work Item filters were
applied to the branched Document.
• Copy Status and Workflow Signatures: Copies the Status and Workflow Signatures of the
Documents.
Only applicable for Documents picked from revisions other than the HEAD that do not use Filter or
Overwrite Work Items.
• Overwrite Work Items: Creates copies of all the Work Items in the Document(s) referenced
from the Master Document(s) so that you can edit them in the branched Document(s).
You must Overwrite each Work Item manually if you Branch a Document from the
menu.
Hover over the icon in the Document Properties sidebar to see what Work Item fields were
reset in a branched Document.
7. (Optional) Hover near the ? on the top right of the dialog box and click to copy your settings in
JavaScript form.
(You can use it in Page scripts to automate the process in the future.)
8. Click Branch.
You can copy the Settings you use when you Branch Documents in JavaScript for use in Pages.
Example
javascript:top.branchDocuments({
documentConfigurations: [
{
sourceDocument: "drivepilot/Requirements/No Spaces at the End",
sourceRevision: null
},
{
sourceDocument: "drivepilot/Requirements/Feasibility
Study_branched_2310",
sourceRevision: null
},
{
sourceDocument: "drivepilot/Requirements/Feasibility Study",
sourceRevision: null
}
],
query: "status:accepted AND severity:must_have",
suffix: "_branched",
updateTitleHeading: true,
copyWorkflowStatusAndSignatures: false,
overwriteWorkItems: true,
initializedFields: ["severity", "assignee"]
});
Procedure
2. Hover near the ? on the top right of the dialog box and click .
3. Open or Create the new Page that you want to add the button to.
9. Add button label text (for example, Branch Documents) to the Label field.
10. Click Apply.
A Document can be configured to contain multiple Work Item types (see Multiple Work Item Types),
and types may be added to a Document at any time. When multiple types are configured in the Work Item
Presentation, then any Work Item type in the Document can be changed to any other configured type.
Example
• A Document might initially be configured to contain only Software Requirement type items.
• You decide to add System Requirement type items and change the configuration accordingly.
• You later determine that some of the existing Software Requirement are actually System
Requirements.
Warning
• The Work Item Link Rules in the project configuration are not checked when a Work Item's type is
changed. If the changed Work Item has linked Work Items, the links should be checked to ensure
that the link roles are still valid for the item's new type.
• If the item has custom fields, it is possible that some custom field values might be converted during
type change, depending on the configuration of the target type.
• Work Item type changes do not get propagated to Derived or Branched Documents.
Work Item type can be changed via the Document editor or the Work Item editor.
Procedure
1. Click anywhere in the Work Item in the Document body to select it.
2. On the Document Editor toolbar, click the drop-down control beside the Mark/Unmark Text button
and select the desired type on the drop-down menu.
Note
Changing the Work Item type is disabled via the Work Item editor if a Work Item is part of a Derived
Document.
Procedure
1. In the Document Editor, click the icon to the left of the desired Work Item and choose Open Item.
The Work Item opens in the Work Item Editor in a new browser tab.
3. Hover over Change Type to, and on the submenu click the name of the type you want the current
Work Item to become.
Print Documents
You can print a Document to any printing device accessible to the computer you are using. Document
comments and comment markers in the Document text are hidden in printed output (except when
printing the Compare view in the Document history).
Procedure
4. In the dialog box presented by your browser, select the target printer, set any desired print options,
and launch the printing process.
Export to PDF
You can export the content of Documents to Portable Document Format (PDF) and customize the
output options.
You can save the generated PDF to any accessible storage (local or network). Document comments,
and comment markers in the Document text are hidden in the PDF output (except when exporting the
Compare view in Document history).
Administrators can configure the default content of the header and footer in generated PDF
documents, either globally for the repository, or for a specific project. Headers/footers can include such
information as the a custom logo, page name, history revision number, creator's user name, the export
date, current page number and total number of pages, for example, 7/20.
PDF header and footer content can also be configured for individual Documents when you Export to
PDF. This is an advanced configuration requiring knowledge of XML.
You can prevent pages breaks from occurring within Work Items by selecting No Page Break in the
Configure Work Item Presentation dialog box. When selected for any Work Item type, Polarion attempts,
as much as possible, not to have page breaks occur in Work Items in the exported PDF document.
Note
Image or Attachment Previews inserted in a Document are preserved when the Document is exported
to PDF.
Tip
Polarion does not clean up HTML within a Wiki content block. If a block contains invalid HTML, even
though it may look fine in a browser, it may look different when exported to PDF or Word formats.
Recommendation: Use something like HTML TIDY to clean up Wiki block HTML before exporting.
Procedure
2. In the Document Editor toolbar, click and select Export to PDF in the drop-down menu.
The Export to PDF dialog box appears.
Note
If you do not click Configure, the Document will use file name, header and footer configurations
set on the project or global level by your administrator.
5. Click Export.
Tip
You can change the settings and quickly export the same Document again until you close the
dialog box.
6. Save or open the exported PDF. (Options will vary depending on your browser and operating system's
PDF settings.)
Customize PDF Headers, Footers and File Names for a single Document or Page
You can also customize the PDF file name, header, footer, or watermark. In the Export to PDF dialog box,
select the Use template check box, and then click the Configure link beside it. The Configure the PDF
Export Template dialog box appears, containing an embedded XML editor, in which the XML code of the
PDF export configuration for the current Document is preloaded.
If there is no Document-specific configuration yet, the default XML from the project configuration is
loaded, which you can modify and save as the Document's own configuration.
Tip
• To include a watermark image, you must add a <watermark> element to the configuration. (See
Configure PDF Export and Configure Export Watermarks for more information on including
watermarks.)
• You can also configure custom file names so that they're automatically created from a combination of
text, Polarion variables and/or Velocity. (See Configure export file name for more information.)
There is often a need to have more than one version of a Document in progress concurrently. For
example, the requirements specification for version 1.0 of a software application might be completed,
and development and testing have begun while work begins on the requirements for version 2.0.
In cases like this, teams can branch the Document containing the version 1.0 requirements
specification to create a specification for version 2.0.
The Requirements in the version 2.0 Document are referenced from the version 1.0
Document.
• Authors can create new Requirement type Work Items applicable to version 2.0 in the Branched
Document.
• While that work is in progress, Requirements contained in the Master Document and appearing as
referenced items in the version 2.0 specification might need to be updated for version 2.
• Authors of the version 2.0 specification can overwrite Requirements referenced from the
version 1.0 Master Document with updated content applicable to the 2.0 version.
• Then, at some point — a release, for example — it becomes desirable to merge the changed Work
Items in the version 2.0 Document into the Master Document so the master is in sync with the
latest release. During the cycle, some items in the Master Document may also have changed, and these
changes need to be reflected in the version 2.0 Document.
Tip
This topic covers how to merge Document changes. See Branching Documents to learn how to make
branched copies tied to an original (Master) Document.
There are two ways you can merge Work Items in Polarion:
• Manually merge Work Items between two Documents, including but not limited to a Branch
Document and a Master Document.
This topic outlines the various merge actions you can use for Manual and Automatic merges.
Tip
See Differences between Manual and Automatic Merge to learn what each can and cannot do, as well
as their limitations and known issues.
Merge Terminology
• Source Document
Available actions for Manual Merge appear in the Merge sidebar on the Work Items comparison page of
the Documents selected for comparison.
For any selected Document or Work Item, the Merge sidebar only displays the valid merge actions for the
selection in each merge direction.
Note
• Project managers can opt to disallow some actions, and an administrator can change the Merge
Actions configuration so that disallowed actions are never available in the sidebar. (So you might not
see some of the actions listed here.)
• You cannot use Merge on Derived Document because changes to Derived Documents are
forbidden.
Actions for Automatic Merge are preconfigured by administrators and automatically applied when
someone initiates an Automatic merge.
Insert actions
Insert actions can be applied if an item in the Source Document does not exist in the Target Document.
Note
If a user deletes/removes an item in the Target Document but it is not yet aligned with the Source
Document, Automatic Merge does not create the item again in the Target Document.
• Insert Live Reference: Insert Work Item as a "live" referenced Work Item.
Subsequent changes to the original are propagated automatically.
• Insert Frozen Reference: Insert Work Item as a referenced Work Item "frozen" to the current revision
of the Source Item.
Subsequent changes to the source item do NOT propagate automatically.
You can manually update the reference to some future revision of the source item.
• Copy the Work Item: Copy the Work Item to the Target Document creating a traceability link to the
source Work Item.
The Work Item in the target Document will be a static copy, not a reference.
Never updated unless manually replaced by another copy or field changes are aligned by the merge
fields action.
Replace actions
These actions are only available for Manual Merge and only if the target is an overwritten Work Item.
• Replace Overwritten Work Item with Live Reference: Send an overwritten Work Item in the target
Document to the Recycle Bin, and replace it with a "live" referenced Work Item. Subsequent
changes to the referenced item are propagated automatically.
• Replace Overwritten Work Item with Frozen Reference: Send an overwritten Work item in the target
Document to the Recycle Bin, replace it with a referenced Work Item from the source Document,
and freeze the reference to the current revision of the source item. Subsequent changes to the source
item will not propagate. You can manually update the reference to a future revision of the source item.
Delete actions
Delete actions can be used if an item in the Target Document does not exist in the Source Document.
Note
Delete actions are not applied by Automatic Merge if Work Items were added to the Target Document,
but the insertion is not yet aligned with the Source Document.
• Delete Reference: Delete the referenced Work Item from the target Document.
Available if the Target Item is a reference to a Work Item that does not yet exist in the Source
Document.
• Send Item to Recycle Bin: Remove Work Item from the target Document but keep it in the Recycle
Bin.
Available when the Target Item is not a referenced Work Item.
• Delete Work Item: Delete Work Item from the Document and the repository (but not from History).
This action is disabled and not visible to users who perform Manual Merges and is not included in the
Automatic Merge default configuration.
Caution
Allowing the deletion of Work Items should be considered carefully.
It may not be acceptable in regulated industries where process transparency and proof of compliance
are required.
If project management decides to allow it, an administrator can enable the action in the Merge Actions
configuration and Automatic Merge Actions configuration.
Referencing actions
• Freeze Work Item Reference: Freeze the Work Item reference in the Target Document at a specific
revision of the Source Item.
Available when the Target Item is referenced from the source Document.
• Unlink and Insert Live Reference: Insert Work Item as a "live" referenced Work Item. Subsequent
changes to the original are propagated automatically.
The existing traceability link between the Source Item and Target Item are removed.
Both the existing target Work Item and the new referenced Work Item appear in the Target Document.
Available when target is an overwritten item from the source Work Item.
• Unlink and Insert Frozen Reference: Insert a Work Item as a referenced Work Item "frozen" to the
current revision of the Source Item.
Subsequent changes to the source DO NOT propagate automatically.
The existing traceability link between the Source Item and Target Item are removed.
Both the existing target Work Item and the new referenced Work Item appear in the Target Document.
Available when the target is an overwritten item from the source Work Item.
Merge fields actions are available for Manual Merge if the merge target is a Work Item and...
• The Target Item is one that was branched, then overwritten in the branch, or...
• The Source Item is frozen to a revision, and the Target Item is contained in the Target Document (i.e.
not referenced)
and source and target Work Items have field changes that can be merged.
• Merge Some Fields: Merge fields specified in the Merge Actions configuration.
By default this includes Title, Description and Test Steps, but this can be changed by an administrator.
• Merge All Fields: Merge all fields of the Work Item that are supported for merging.
Merge field actions are applied for Automatic Merge if non-conflicting changes are detected for field
values of the original Work Item and the field values of its overwritten copy in a branched Document.
Manual Automatic
Action Merge Merge
Insert actions: Available if the Target Item does not exist.
Tip
Automatic Merge's Work Item Field changes are more granular than Manual Merge.
• If the Manual merge Field action is applied, the different values of all Work Item Fields (except
unsupported fields), from the Source Document's Work Items are applied to their counterparts
in the Target Document.
• If the Automatic Merge field action is applied, then only the values changed in the Source
Document are propagated to the Target Document. (Work Item Fields changed in the
Target Document are left untouched.)
• See Merge limitations and known issues.
Polarion's merge feature is continuing to improve and expand in scope. Here are its current limitations and
known issues.
(This includes content added via the Insert Menu menu to the Document itself.)
• If a compared Work Item has a new attachment, when merged manually or with Automatic Merge,
the attachment is flagged as a newly discovered difference when comparing Documents. The new
attachment is also flagged as a new change in subsequent merges, even though it is no longer a newly
added item.
• Newly merged Work Items may be misaligned relative to neighboring free text.
• Automatic Merge is only available between the HEAD (most recent) revisions of the Master and Branch
Documents. You cannot merge from historical revisions.
• If Work Items are sent to the Recycle Bin in both Documents and then restored in one of the
Documents, they are not processed by Automatic Merge Insert actions.
Tip
If you are in this situation, go to Compare view and apply your changes manually.
Tip
Limit deleting Work Items in the Branch Document and both Push and Pull when you do.
If you do not, you may have to manually merge to remove these Work Items from the Master.
(You can also Unmark the Work Items in the Branch Document to remove them from the Master.)
If you merge Work Item changes manually or Automatic Merge discovered conflicts, you can compare
the Source and Target Documents.
Procedure
1. Open the Document you want to compare with another one. This can be a Master or Branched
Document.
2. Select a Document to compare the open Document with.
a. If the open Document is a Branched Document, click Actions, and select Compare
with Master Document.
b. If the open Document is a Master Document, click Actions, and select Compare
with Other Document.
3. Select the Project, Space, and Document you want to compare the open Document with.
The Document's head (newest) revision is used for the comparison unless you click HEAD and select
a different revision.
• If the open Document is a Master, select a Branched Document.
• If the open Document is a Branched Document, select the corresponding Master Document.
Tip
If you know Lucene syntax, you can enter a Lucene query in the Filter field to limit the comparison
to a subset of all the Work Items in the specified Document.
Example: status:approved OR status:done
4. Click OK.
The Document's Compare view opens provided that the total number of Work Items in both
Documents does not exceed the limit set in the system configuration. The default limit is 1000.
If exceeded, there is an intermediate step where you can choose specific things to compare, such as
Document, Work Items, or Fields.
Note
The default limit provides best system performance in most cases. An administrator can adjust the
limit up or down in the following system property:
com.polarion.ui.documentCompare.workItemsLimit.
When you Compare Master and Branched Documents a comparison of Document changes appears first.
◦ Click Export to PDF to convert a copy of the Document to the Portable Document Format (PDF).
• Removed items are highlighted in . Added items are . Formatting changes are .
• Appears if you filtered the comparison. Hover over the icon to see the applied filter.
Click Work Items at the top right to only view Work Item changes.
On the left is the Document you started with, and on the right is the Document you want to compare it
to.
Tip
• Items with no changed fields to view all Work Items. (Even those without any changes.)
Displays all changed fields and pairs of overwritten or frozen Work Items with no changed fields.
• Items filtered out on one side. (Only appears if a filter is used before comparing.)
When selected, if a Work Item pair is tagged with Filtered out on one of the two sides, they appear
in the comparison.
1
(They appear in the order that they are structured in the Document on the left.)
For Work Items that are changed, it is easy to see under which
chapter they are located and whether there are parent Work Items.
Headings and parent Work Items appear only to reveal the structure, and it is not possible to perform
merge actions with them.
You can easily see the structure of Work Items, and the differences in the two Documents.
Work Items that exist only in one of the Documents also appear in the actual or potential post-merge
structure of the other Document.
Example
Items that exist only in one Document appear in the second Document where they can be added via
Merge.
A Work Item that was overwritten in one Document is compared on single line with the original Work
Item it was branched from, or another overwritten item that has the same original Work Item.
To better understand why Work Items are compared on one line, as well as for better decision making on
merge actions, some additional information is displayed on each Work Item's header:
• Frozen reference to rev # : Appears if Work Item is referenced from a specific revision.
• Live reference: Appears if a Work Item is referenced from its Head revision.
• Branched from [ID]: Appears if a Work Item was referenced from one Document and was overwritten
in the other.
• Item is in Recycle Bin: Appears for a Work Item that once existed in the Source Document but was
sent to the Recycle Bin, and the Document you are comparing it to still contains a reference to it.
• Does not exist : Appears if a Work Item does not exist in the Document, or is in the Recycle Bin
(except the case above).
If a Work item has no additional information in the header it means that the Work Item is contained in the
Document. That is, it is neither a reference nor a branched item.
Note
Repair missing cross-references
You can repair missing cross-references by inserting the missing item using the Insert Live/Frozen
reference merge action.
The Merge sidebar shows available merge actions for a selected Work Item in a given context, and allows
you to perform merges.
To access the sidebar, click (Merge) on the Work Items page of the Document comparison view.
Note
You must have permission to view both Documents, permission to modify any Document changed by
a merge action, and permission to modify Work Items in a changed Document. If you do not have the
necessary permissions, the sidebar is disabled.
When Merge sidebar is open you can select a Work Item by clicking on its header.
Work Item headers are light blue. Also, the left border appears highlighted, which helps you to easily see:
• Which Work Item is currently selected: the header of the Work Item and the left border are highlighted.
• Which Work Item has some pending merge action. The left border color changes to the color of the
pending merge action in the sidebar.
The border color remains if you select another Work Item, until the changes are saved.
• That a Work Item has no pending merge action and is not selected: the left border is gray.
When you select a Work Item, the Merge sidebar shows the merge actions available for the current
selection.
(For a complete listing and description of merge actions, see Merge terminology and actions.)
• The arrow buttons at the top show the merge direction. (Master to Branched, or Branched to Master.)
• If an arrow button is disabled, no merge actions are available in that direction for the selected Work
Item.
• Click an enabled arrow button to see the merge action(s) available in that direction for the selected
Work Item.
Merge from left to Available merge Merge from right Different set of
right actions to left available actions
• In the Merge sidebar, click the merge action you want to run.
If you make a mistake and find you are looking at the wrong merge action direction or you don't want
to do any merge action, click Cancel, or the selected arrow button, or the other arrow button if it is
enabled.
• You can optionally select merge actions for different Work Items without saving.
After you have selected all the merge actions you want for all Work Items, click Save at the bottom of
the Merge sidebar.
An administrator can configure which merge actions are available to users. For example, if project leaders
decide that the Copy the Work Item action should never be available, the administrator can remove it
from the configuration. For more information, see Configure Manual merge actions for Documents.
Note
You cannot use Merge on Derived Document because changes to Derived Documents are forbidden.
Concurrent changes in one or both Documents involved in a merge action are generally rare, but they
can occur.
Polarion always notifies you if another user has made concurrent changes to the same Document you are
working with, and displays messages explaining your options.
Click Review changes to view the changes made by another user so you can decide whether to keep or
overwrite them.
Automatic Merge is Polarion's tool to automatically merge Document Work Item changes.
Example
You need to Branch a Document but also continue concurrent work under both the Branched
Document and its original Master Document.
As time passes, changes in both Documents emerge and you need to propagate changes bi-
directionally.
Polarion's Automatic Merge lets you automate the process of merging the changes between these two
Documents.
Automatic Merge compares the Work Items of a Master and a Branched Document, finds the
differences, and automatically merges non-conflicting changes.
You can find Automatic Merge ( Merge ) in the Document Editor's Action menu.
Push to Master: Work Item changes in the Branched Document are propagated to the Master
Document.
Pull from Master: Work Item changes in the Master Document are propagated to the Branched
Document.
• Insert new Target Work Items as copies or live/frozen references of new Source Work Items.
• Delete and Unmark Target Work Items when their corresponding Source Work Items are deleted.
• Update Target Work Item field values to match the Source Work Item's values.
Note
• Merge is only available if a Document is a Branched Document.
• You must have permission to READ both the Master and Branch Documents.
• You must have permission to MODIFY the Branch Document.
(You must also have permission to MODIFY the Master Document if you want to Push to Master.)
• Automatic: Polarion automatically applies configured merge actions and propagates all non-
conflicting changes it finds to the target Document.
(The results are listed in a report.)
• Automatic with Preview: Before applying changes and saving, Polarion lists all the changes it
plans to make so you can review them first.
• Manual Merge: You can also manually merge Master and Branch Documents.
Both Documents appear in Compare view, where you can manually view and merge each
change.
Caution
Once the results of an Automatic Merge are saved, they cannot be reverted automatically.
If you do not want to create a Document Baseline, deselect Create Document Baseline.
Note
If you do not have permission to create a Baseline but the permissions needed to Merge, the
Create Document Baseline option is disabled.
5. (Optional) Add a Filter to limit the Source Work Items whose changes will be merged to the Target
Document.
Tip
If you know Lucene syntax, you can enter a Lucene query in the Filter field to limit the comparison
to a subset of all the Work Items in the specified Document.
Example: status:approved OR status:done
• If new items are found in the subset of filtered Source Items, they are inserted, and the
appropriate new Target Items are created.
• If changes are detected in the filtered Source Items, then non-conflicting changes are merged to
the corresponding Target Items.
• No Target Items are deleted when a Filter for Source Items is used.
• Example
If you only want to merge Approved Requirements from the Source Document.
• When Automatic Merge is used for a Master, with a branch Document created with a Filter:
◦ The original filter information is rendered as a Filter applied to the Master Document and
cannot be edited.
◦ If you Pull from the Master and the Master is the Source Document, you can add another
Filter to limit Master Work Items even more.
◦ After creating a branch based on a Filter, you can add Document Work Items to the branch
that do not match that original filter. Automatic Merge covers these Work Items since the
original filter is only applied to Master Work Items.
Example
If you create a branch based on a customFields:most_important_items filter, then add
some items that fall outside this filter to the Branch Document; when you Push to Master,
those items are propagated to the Master Document. The items (both the master and the
branch versions) are then covered by the Automatic Merge algorithm.
Tip
Valid only for Push to Master where a Branch Document is the Source Document:
a. You can apply a filter to a Document.
b. When you Push to Master, the filter propagates to the Filter field in the dialog.
(You can adjust it, if needed, before proceeding with the merge.)
Tip
Learn how Polarion's Merge algorithm works.
If the Merge completes successfully, you can view the details. If it fails, you are given an explanation.
• Listed changes
• View details with Show Log and Review Changes.
• If there's an issue with the merge.
• If there's no change to the Target Document.
Listed changes
• The number of Work Items that were deleted or unmarked (sent to the Recycle Bin).
Note
Target Work Item changes are counted in more than one of the listed details.
Here's an example:
If Automatic Merge detects that several results were valid but there were also conflicting fields in a
Work Item update, then the Work Item appears as both updated and with conflicts that you must
resolve.
The applied configuration is listed in the job log each time it is executed.
• Click Review Changes to compare before and after merge versions of the Target Document.
Tip
You can also view merge changes in the Baseline Description.
If you did not deselect Create Document Baseline during an Automatic Merge, you can also view
merge details in the Description of the Baseline's details.
If there is an issue while executing (for example, a Document was deleted mid-merge), you receive a
report that the merge failed with an explanation.
You can also have merges that make no changes in the Target Document.
If that's the case, no new revision is created for the Target Document and you can click Show log to view
the merge details.
Note
• If an action is not configured for the Automatic Merge or cannot be applied due to configured
conditions, then no changes are made during the merge.
• Ask your Administrator to check the Automatic Merge configuration if you get an unexpected result.
This topic covers how Polarion's Automatic Merge algorithm merges Work Item Field values. The merge
field action for Automatic Merge is more granular than that for Manual Merge:
• Manual Merge works at the Work Item level
• Automatic Merge merges changes to the Work Item Field level.
Whenever someone overwrites a reference to a Master Work Item in a Branch Document, it retains a
traceability link to the Master Work Item revision aligned with those Branched Document's values.
To determine if Automatic Merge should update a Target Work Item's Field value to match the Source
Work Item, Polarion compares each field value of the Source Work Item with the Master Work Item in
the revision where the Branch Work Item fields were aligned with the Master's Work Item Field values.
When an Automatic Merge begins, Polarion checks for changes in the Source's Work Items. If it detects a
change, it compares it to the same Work Item field value in the Target Work Item.
Example
1. A Work Item in a Document has three fields with the following values: value1, value2 and
value3.
If someone selects Pull from Master, Field 3 of the Branched Work Item changes to the value from
the Master, and the revision in the is_branched_from link is updated to point to the Master Work Item
that had all its changes propagated to the Branch.
Then, if someone selects Push to Master, Field 1 and Field 2 of the Master Work Item get
updated to the values from the Branch Work Item, and the revision in the is_branched_from link is
also updated. (Because all Branched Work Item changes are propagated to the Master Work Items.)
Note
Push to Master changed one Document.
• Automatic Merge creates a new revision (the Target Document) for the Master Document.
• A new revision is created for the Branch Document since the revisions and traceability links between
the Master and Branch Work Items are also updated.
• A new revision is only created for the Branched Document. (The target of the merge.)
• Traceability links are also updated in the Branched Document in the same revision.
When an Automatic Merge is complete, you are notified of these conflicts and must resolve them.
Procedure
Note
If you change the field to the same value for both the Source and Target Work Item, Polarion does
not consider it a conflict and updates the Master revision in the is_branched_from link for the
Work Item in a Branched Document.
If some changed fields in the Source Work Item cannot be propagated to the Target Work Item due
to configured limitations (a field is read-only in the Target Document, or the user has limited per-field
permissions), then Automatic Merge doesn't consider the Source and Target Work Items as aligned until
the limitation is resolved, and reports that they were skipped in the result dialog.
• If there are no conflicting changes between the Branch and Master Work Items, but different fields are
updated for both Work Items and you Push to Master, you could potentially lose data in subsequent
merges.
To prevent this, Polarion recommends that you Pull from Master to propagate all Master changes to
the Branch Document first.
(When this occurs, Automatic Merge does not even partially update the target Work Item.)
• If Automatic merge detects that a Pull from Master is required and conflicts were detected:
If you are sure that you do not need to Pull from Master and that there is no risk of data loss, you
can Compare and manually merge Work Items.
Automatic Merge can insert new Work Items to the Target Documents if:
Note
• If the Target Document's Work Item Presentation Configuration is missing the Work Item Type you
are trying to insert as a copy via merge, then the insert action is skipped.
(Even if the Automatic Merge configuration has Insert Live/Frozen Reference Work Items as an
insert action with the next priority.)
• If Insert Live/Frozen Reference Work Items is enabled in your Automatic Merge configuration, but
the Work Item Presentation Configuration of the Target Document does not support it, the items
are still inserted but a hidden layout is added.
Automatic Merge can remove Work Items from the Target Document if:
Sign Documents
Background information
Polarion supports a process of review and approval of individual Work Items, such as requirements. These
may be contained in Documents, or created directly in the Work Item Tracker. For more information,
see Reviewing and Approving Work Items). However, it can be desirable, for regulatory compliance and
other reasons, to have such a process for entire Documents, such as requirements or design specifications.
Polarion can support your formal review and sign-off process for specifications and other types of
LiveDoc Documents, using secure electronic signatures compliant with U.S. 21 CFR Part 11. A Polarion
administrator can map your review and sign-off process to the Document workflow configuration. Each
step in the process can optionally be set up to require one or more electronic signatures before the a
Document can move to the next stage in the workflow.
Consider a simple example. Suppose a requirements specification Document goes through three stages
before the requirements can be implemented in production: Draft, In Review, and Approved. An
administrator can map these status values in the project workflow configuration for Documents of the
type Requirements Specification. It is possible to configure as many Document types as you need. You
might have more granular types like System Requirements Specification, Functional Requirements
Specification, and types like Risk Analysis. The Document owner or manager can invoke actions to move
the Document through the process from one status to the next. These status values can also be defined in
the Document workflow configuration, and could be something like:
• Send to Review — This action transitions the specification Document from the Draft status to the In
Review status.
• Mark Approved — This action transitions the specification Document from the In Review status to the
Approved status.
Tip
Polarion includes project templates that have Document types and Document workflow already
configured. The templates are based on input from actual users and are designed to meet the needs
of a broad range of projects. Both project templates, and projects created from them can be customized
to meet user-specific requirements.
Administrators can configure Polarion to authenticate users using different authentication methods.
Depending on the method used, electronic signatures for Documents and Work Items may work
"out of the box", or some additional method-configuration may be needed. Administrators setting up
authentication may now always be aware of users' need to use electronic signatures. If documented
electronic signature functionality is missing for you, consult your administrator.
Regulatory compliance
For regulatory compliance, it is necessary to record who reviewed the specification Document, who
approved it, and when. The administrator can configure the Mark Approved action to require signatures,
and a signature policy such as all invited reviewers must sign, or at least one invited reviewer must
sign. When so configured, no one can set a requirements specification Document's status to Approved
until all the necessary signatures have been registered.
Caution
Prevent Users from Saving Passwords in Chrome:
Administrators should ensure that all their users have password saving turned off in Chrome to comply
with U.S. 21 CFR Part 11 and other regulatory standards governing electronic signatures.
Electronic signatures for Documents are compliant with United States Code of Federal Regulations, Title
21 Part 11 (CFR 21 Part 11). Users who sign a Document workflow action are shown a dialog advising
them of the significance of their signing action, and prompting them to enter their password to confirm
their signature and identity. A record of each signature, including data that makes it CFR 21 Part 11
compliant, is recorded automatically in the Document
To collect signatures, the specification Document's owner or manager invites people to review and sign
it by sending them an email containing a link to the Document in the Polarion portal. All invitees must
have user accounts and the permissions required to access the Document, and to sign or decline to sign
Documents. Each reviewer is presented the option to sign or decline to sign. They can also post comments.
After all the necessary signatures have been registered, the Document owner or manager can invoke the
Mark Approved action in the Document properties, and the Document transitions to the Approved status.
The signature process can support multiple versions. For example, the specification may be approved
for production, but while production is going on, work resumes on the specification, adding new
requirements for new features, or enhancements to existing features. The specification Document having
the Approved status becomes read-only. However, is not necessary to create a different Document to
continue development. The workflow can be configured with an action named something like New
Version, which branches the approved Document, which can then be tagged with a version identifier
and modified as needed for the next round of production. The previous version in its Approved state,
is automatically preserved in the Document history. The project manager might also create a Document
Baseline and/or a Project Baseline at the point which the specification was signed as approved.
This section contains information for authors and/or managers of specification or other Documents. It
covers what you need to know in order to set up a review and sign-off process for your Documents.
Start by working with the Polarion administrator for your project to review the Document Types and
Document Workflow configurations to make sure the types you need exist, and that each type has your
process mapped in the workflow. Decide which transition actions must require signatures, and have each
action configured accordingly in the Document workflow configuration. Information for administrators
is provided in Configure Document Signatures. Depending on the project template used to create the
project, very little if any modification may be needed.
With the Document signatures configuration in place, there is nothing more to do except develop your
Document up to the point where it is ready for the workflow transition that requires signatures — or the
first such, if there is more than one. For example, your Document starts with a Draft status, and at some
point is ready for review and approval. Following the simple scenario described earlier, you would invoke
the Send to Review action. The action is enabled in the Status field in the Document Properties because
that action was not configured to require signatures in order for the transition to In Review status to take
place.
However, you see that the next action, Mark Approved, is disabled in the Status field. This is because
the action is configured to require signatures. You won't be able to invoke that action and transition the
Document to the Approved status until signatures are logged. It is at this point that you need to invite
people to review and sign your Document.
Everyone you invite must have a Polarion user account, and have permission to read Documents in the
project. Otherwise, they cannot to see your Document and receive an error message if they follow a link
leading to it. All reviewers must also be assigned the project role that has been granted the SIGN/DECLINE
permission for Documents. Otherwise, they do not appear in the list of people you can invite to review and
sign your Document.
Procedure
1. Open the Document in the Document Editor, and open the Signatures sidebar.
The sidebar shows a panel labeled with the name of the workflow action that requires signatures. In
the case of our running example, that would be Mark Approved.
2. Click the action name. The sidebar shows two page tabs and a button.
Tip
You cannot invoke the transition action until the configured signature policy is satisfied. For
example, if the policy requires all invited users to sign, the action cannot be invoked until all
have logged a signature. If it requires that at least one must sign and none must decline, then that
condition must be satisfied in order to invoke the action.
You can view the signature policy in the All Signatures tab of the Signatures sidebar, shown after
you click an action name. See the previous figure.
5. At the bottom of the dialog, select the URL in the Link for Invitees text box and copy it to your
clipboard.
The following figure illustrates an email message to invite people to review and sign a Document.
When sending a message to your reviewers, include the Document URL. Paste the Document URL from the
Invite for Signature dialog box.
Your administrator can predefine the list of invitees for any Document workflow action, so that the
Document owner/manager does not have to add invitees manually for every new Document. Invitees can
be added according to their user role in the project, or explicitly by their user ID. You might want to
consider having custom user roles defined for your project and have those roles assigned to the people
who routinely review and approve specifications or other kinds of Documents.
Monitor signatures
You can monitor the progress of collecting signatures in the Signatures sidebar of your Document. The
sidebar shows which invitees have signed, which have declined, and the names of all invitees.
The All Signatures tab of the sidebar shows this same information, plus the signature policy.
If the signature policy is currently satisfied, a message displays indicating this. A link is provided that opens
the Document Properties sidebar. You can then invoke the action to transition the Document in the
Status field, where the action is enabled. Be sure to save the Document after changing the field.
Sometimes feedback from invited signers reveals that additional work on the Document is necessary.
In that case, another round of reviews needs to be started. The Document owner/manager can reset
signature status of Signed or Rejected for the current workflow transition back to the Pending state by
clicking on the X icon on the right part of the signature Statistics. The Reset action is available only in
the All Signatures panel for a specific workflow transition — the is, not in My Signatures, and not in
Entry Point). It is not available after the Document status has been transitioned. You can see recalculated
signature statistics immediately without saving the Document.
In cases where a Document needs to be reworked, or a signature was declined, the author or owner may
decide that signatures up to that point are obsolete and a new round of reviews and signatures is needed
on a new, reworked Document version. To accommodate such scenarios, an administrator can configure
the workflow action that sends the Document back to the authoring status — Back to Draft) to run a
workflow function that marks the current signatures as obsolete.
After all signatures needed to satisfy the signature policy have been logged, the Signatures sidebar
displays a message indicating that the Document can now be transitioned to the next Status. You as the
Document owner, author or manager must explicitly take this action.
Procedure
Note
To be able to transition the workflow, you must have the MANAGE SIGNATURES permission for
Documents, assuming your system has the default configuration of workflow signatures.
As you can see in the above figure, when signature policy is satisfied, the workflow transition action is
enabled.
Tip
When the signature policy is satisfied, the All Signatures tab of the Signatures sidebar displays a link
that, when clicked, opens the Document Properties sidebar, where you can change the Document
Status.
In projects based on Polarion Project Templates, requirements specification type Documents are
preconfigured with Document workflow and permissions settings that make such Documents read-only
once they have reached any other than the Draft status in the workflow. The prevents modification
of any Requirements Specification Document that was submitted for review or approved. Documents
can be branched to store the approved version of Document for implementation, while the master
specification can be worked on for a subsequent version or release. For technical details, see Document
Signatures Custom Set.
Review this topic of you have been invited to review and sign a Document in your organization's Polarion
portal, but are unsure what you need to do.
Access a Document
Normally you receive an email or other electronic message from the owner of a specification or other
Document requesting your review and signature. This message should contain a link to the Document in
your organization's Polarion portal. Simply click the link to open your default web browser and navigate to
the Document in the portal. If you are not already logged on, you must do so, after which the Document
you need to review opens. The Signatures sidebar should be visible, and the My Signatures tab selected.
If you are already logged on to the portal, Documents awaiting your signature are listed, with links, in your
My Polarion page (assuming the page has not been customized to remove this listing).
Signature options
After you have reviewed the Document, you have three options:
1. Sign — Click the Sign button in the Signatures sidebar. You can optionally add a comment.
By this action you signify that you agree that the Document in its current state can transition to the
next step in the workflow.
2. Decline — Click the Decline button. You should also add a comment stating your reasons for
declining.
By this action you signify that you do not agree that the Document in its current state can transition
to the next step in the workflow.
3. Add Comment — State questions or discussion points for the author or other stakeholders, without
signing or declining.
By commenting only, with no other action, you may be blocking the Document from moving to the
next step in the workflow, depending on the signature policy configured for the action you are asked
to sign. You can see the signature policy in the All Signatures tab of the Signatures sidebar.
Warning
After taking one of the above actions, be sure to click Save on the Document Editor toolbar, or
use the Save keyboard shortcut to save the Document. If you leave the Document without saving, your
signature action and any comments are not logged.
When you sign a Document, you are not necessarily signifying final approval of the Document. You are
only signifying that you agree that it can move to the next stage of the development process, as configured
in the project workflow. For example, you may have been asked to sign the workflow action Send to
Review, that transitions the Document's status from Draft to In Review. By signing, you signify that you
agree that the Document is ready to that transition.
Document-related signatures are U.S. CFR 21 Part 11 compliant secure electronic signatures. When you
click Sign, a dialog box appears showing a message asking you to explicitly enter your user name, followed
by one asking for your password. There are two steps to ensure that the electronic signature is compliant
with most standards.
The automated Document history records the data required for regulatory compliance, including your user
name and the date-time of your signature.
The action may be configured with a signature policy such as all invited users must sign. Even if your
signature results in the signature policy being satisfied, the action of signing does not actually perform
the workflow action and transition the Document to the next Status. The Document author or owner or
manager must explicitly do the transition in the Status field of the Document Properties sidebar.
Signature comments
Throughout the process of obtaining signatures for various Document workflow actions, stakeholders
can have discussions by posting comments that pertain specifically to the signature process. Such
Signature Comments have several commonalities with Document Comments, which are not related
to the signature process:
• The same options are available by clicking icon on the sidebar header.
However, Signature Comments are created in the Signatures sidebar, in the Signature Comments
section, using the Add Comment button. The comments become part of the history maintained for
the Document signature process. The Signatures sidebar shows only unresolved Signature Comments,
allowing signature stakeholders to find them easily and not be distracted by Document Comments.
Users must be granted the permissions required to create, reply to, and resolve comments in order to
perform these operations.
Tip
If you have already signed a transition and logged the required signature comment, and the Document
owner subsequently resets the signature process, your previous signature comment must be marked
Resolved before you can sign the document again. If necessary, you are prompted to resolve your
previous comment when you sign the Document again.
You can optionally display a panel of information about the current status signatures in the body of a
Document. The#documentPanel macro, when used in a Classic Wiki content block in a Document,
renders an overview of Document Properties as well as overview of Document Signatures for the current
version of the Document.
Procedure
1. Place the insertion point on the line where you want the panel to appear, for example, after the Table
of Contents.
2. On the Document Editor toolbar, click the Insert drop-down control, and choose Wiki Content.
3. In the Wiki Content dialog, enter the documentPanel macro with the desired parameters and click
OK. For details on parameters, see Syntax Help in the Classic Wiki Editor.
Example: #documentPanel(true "approved") - shows Document signature that are not done
yet, and specifies the ID of the workflow status representing the final approved status of the
Document.
Tip
Classic Wiki Syntax Help is normally available on your Polarion portal at a URL like the following:
Changes in Document workflow signatures are shown in Document history when comparing two revisions.
Information is shown in the Fields section.
When you open the Signatures sidebar, it shows all signed transitions — those for which the signature
process is complete. Clicking on a name opens a historical view of the Document in the state it was when
the transition was signed.
This is and advanced topic for developers and power users who want to formulate and run queries on
Document signatures. Two indexed fields are available for searching for Documents by signature.
• signatureState —The overall state of the active workflow signature; specifically, for the next workflow
transition. The goal is to be able to easily query Documents that are in certain state of the signature.
Possible values: pending, declined, or ready.
• signatures — Search for Documents by individual signatures and their outcomes for the active
workflow signature; specifically, for the next workflow transition. The goal is to be able to easily query
for Documents that are waiting for my signature. Possible values: pending, signed, or declined.
Syntax: signatures:[VERDICT]=[USERID OR *]
Examples:
1. signatures:invited=$me OR signatures:invited=$[user.id]
The $me variable works only in Classic Wiki content. Dollar sign needs to be escaped in Classic Wiki as
\$. Search all Documents where current user is invited to sign the active transition.
2. signatures:signed=* — Search all Documents for which the active transition has been signed by
any user.
3. signatures:declined=bJones — Search all Documents for which the active transition has been
declined by the user bJones.
Usage:
Procedure
If you Branch a Document that has signatures configured in its workflow, you can optionally include the
signatures. The Branch Document dialog provides an option, Copy Status and Workflow Signatures that
controls whether signatures are copied. If the option is selected, then on the branch, the action does the
following:
Branching with workflow and signatures is only available from a specific Document revision, not the head
revision. If you try to branch the head revision, you are automatically switched to the last revision and
asked to confirm the switch.
Collections
What is a Collection?
Collections support parallel development activities, help with audit and regulatory compliance and
support advanced reuse scenarios. At first glance, it may seem like Collections are simple containers for
live documents, but there is more to it than that.
If your organization falls into this category you can Create a Collection of Documents to help manage the
scenario described below.
Note
All Polarion users will be able to READ Collections, but you'll need a REQ, QA or ALM license to create
and edit them.
Complex Waterfall (V-model) product development is often used in heavily regulated industries
(Aerospace, Defense and Automotive to name a few), and its not unusual to have different phases of
development done by different teams. It's also not unusual for specifications to be developed concurrently
or in parallel with one another.
Tip
You can add Documents to a single Collection from one or more Polarion Projects.
The Polarion Collection concept helps projects with that concurrent workflow. It helps them to ensure they
are working with the right versions of specifications, links that are created point to the correct specification
versions, and the collection can be archived for historic and regulatory compliance needs.
TEAM A
TEAM D
TRACE
LL Software LL Software LL Software
Product Delivery
(Release 1) Specification Specification Specification
Version 1 Version 2 Version n
TIME
Phase 1 of the project begins, and Team A starts their work and at some point, they finish Version 1 of
the product Need specification. At this point, (in a waterfall development process), Team B starts working
on their System level specification. As they develop their specification based on Version 1 of the Product
Need specification, they develop traceability from the System Level specification they are working on
back to Version 1 of the Product Need Specification. This is then repeated for the other levels that are
worked on by Teams C and D. In Polarion, now this work can be done inside a Collection.
Once all teams have finished Version 1 of their specifications and have gone through their respective
reviews, Phase 1 of the project concludes, and in order to satisfy regulatory needs, they close the
Collection to represent Release 1 of the product delivery (shown by the red oval in the diagram above).
Thus, the closed Collection now consists of:
Now many companies can’t afford the luxury of waiting for Phase 1 of the product delivery to finish
before they start working on the next phase of their product delivery. So to that end, they will supplement
the classic V-Model lifecycle with a concurrent workflow. To illustrate this concept, Team A would begin
working on Phase 2 of the project and thus work on the next iteration of the User need specification
even though Teams B, C and D are concurrently working on Phase 1 of the project.
Collections ensure that the teams will work with the correct versions of the product specifications for the
correct product deliveries or releases. As such they will also ensure that any links that get created between
the specifications within the Collection point to the correct versions.
If at any time in the future, the project team needs to go back and review a specific product release,
Collections make it easy to review that information because everything is contained within the scope of
the Collection.
Related Topics
What is a Collection?
Create/Delete a Collection
Add/Remove Collection Documents
Work in Collections
Collection Baselines
Reuse Collections
Close/Reopen a Collection
Configure Collections
Create/Delete a Collection
Note
If the Collections topic does not appear in Navigation, ask your administrator to configure it.
If your administrators have given you the correct permissions, you can Create or Delete a Collection.
Create a Collection
Tip
Administrators can configure Quick Create so users can create a Collection right from the Navigation
Header.
Procedure
Tip
The Description can be added as a column in the current Collections table.
a. Right-click on a table column and click More or beside then Customize Table.
The Customize Table dialog appears.
5. Now you can add Documents and define any configured custom field values.
Delete a Collection
Procedure
Related Topics
What is a Collection?
Create/Delete a Collection
Add/Remove Collection Documents
Work with Collections
Work in Collections
Collection Baselines
Reuse Collections
Close/Reopen a Collection
Configure Collections
This is especially useful for linking because backlinks to Work Items appear in the Document Revisions
or Document Baselines selected for the Collection and all outgoing links from these Documents will
only go to other Documents within the Collection.
Tip
For already added Documents, you can easily replace one revision with another, change a baseline
revision to the HEAD, or any other permutation.
Procedure
4. Here you can add Documents from one or more Polarion Projects, or remove them.
Tip
You can also add Documents from closed or baselined Collections.
5. Select a Project that you want to add Documents from in the Project column drop-down list.
a. Select a Document that you want to include from the Title drop-down menu and click .
6. (Optional) The HEAD (latest) revision of the Document is selected by default but you can also select
an earlier Baseline or Revision by clicking .
The Select Document Revision dialog box appears.
Tip
Not sure what Revision number or Baseline you need? Click the Document History link to view all
available options.
(If it does, select another Revision of the Document or Remove it and Save again.)
Tip
Useful if you want to start a new Collection based on a previous, closed Collection or Collection
Baseline, and then add additional Documents to it.
(Or if you want to switch some Documents to baselines that differ from the original Collection.)
Procedure
5. Select a Project, then select a closed or baselined Collection from the drop-down box
Procedure
Caution
This check can take a while and can be resource-intensive depending on the number of Documents in
the Collection, the total amount of Work Items they contain and the links between them.
Document checks;
• Lists all Documents,Work Items and links in the Collection in the log.
• Looks for duplicate Documents in the Collection.
• Looks for unresolvable Documents in the Collection.
• Reports any links to a specific revision that are not given by the Collection.
• Reports any unresolvable items.
• Reports all links from a specific revision to the HEAD.
Procedure
Note
When hovering over the Smart Title of a Collection in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Collection link with its Title as the link's label.
You can search for Collections (or Documents within them) in the search bar at the top of the Collections
page.
Procedure
Tip
• If a Document is renamed, you can find it using its new Name if its HEAD is contained
within a Collection.
• See the Advanced Collection search queries section below to learn how to search for a
Document and a specific revision.
b. If you know the name and location of a specific Document, you can find the Collection(s) that
contain it by clicking the Document ID preset and using the following syntax:
"Project ID/Space ID/Document ID": "drivepilot/Design/Software Requirement
Specification"
"Space ID/Document ID": "Design/Software Requirement Specification"
"Document ID": "Software Requirement Specification"
(Double quotes are optional if there is no space.)
2. Press Enter.
The table of Collections is filtered based on your query.
Note
The following queries can be used in the query field, Reports and the API (advanced users).
Procedure
1. To look up the Collection containing a Document in its HEAD revision. (The most recent version.)
elements.documents:"MyProject/Requirements/Project Scope"
• MyProject is the project ID of the Document. (Might differ from the Collection's project.)
• Requirements is the ID of the Document's Space.
• Project Scope is the ID of the Document.
2. To look up Collections containing a specific Document's revision:
elements.documents:"MyProject/Requirements/Project Scope#3849"
• 3849 is the desired revision number.
• The double quotes are only required if there is a blank space in the Space or Document ID.
The query only returns Collections that contain this Document in this revision.
3. To look up Collections containing a specific Document in any revision, but not the HEAD:
elements.documents:MyProject/Requirements/Project\ Scope#*
• * at the end tells Polarion to look for anything after the #.
• This prefix query (with a wildcard * at the end) does not work with double quotes.
• \ is an alternative way to escape a space character, but is only suitable for the
elements.documents field.
For other parameters, wrap the value in double quotes. (\ also shouldn't be used in other presets
or query bubbles.)
4. To look up Collections containing a particular Document in any revision, baseline or HEAD, it is
possible to combine the above:
elements.documents:"MyProject/Requirements/Project Scope" OR
elements.documents:MyProject/Requirements/Project\ Scope#*
An even easier way would be to us the Document ID preset. (Note the .id in the index field name):
elements.documents.id:"MyProject/Requirements/Project Scope"
(This matches all occurrences, whether they're HEAD or baselined.)
You can view a Collection's History to keep track of what Documents were added or removed and
who made the changes.
Changes to the Collection, and who made them are visible in its History.
Procedure
• Document's without a revision number (like 438 in the example above) are in the HEAD revision.
• If no fields are changed, (like when the Collection Baseline was created in the example above),
then no Updated by: is displayed.
(But if you want to know who created the Collection Baseline, click on the baseline button to
jump to the Collection Baseline's details.)
• A Collection's history displays what Documents were added/removed not changes to the
Documents themselves.
4. (Optional) Click on a Revision number link beside a date to view the Collection as it was then.
Note
If you click on a Document in the Collection while viewing it in a previous revision, it will load the
Document in the state that it was at the time too.
Work in Collections
Once you've Created a Collection and populated it with Documents, you can start working in it.
Tip
See Work with Collections to learn how to search Collections and View a Collection's History.
Once you've found the Collection that contains the Documents you're looking for, you can start working
with it.
1. Select Collection in Navigation and click on a Collection from the list of available Collections.
Documents contained within the Collection appear in the Documents section below the table.
Hover over a Document to see a tooltip of its location. (Project / Space / Full name)
Note
Documents in a Revision or Document Baseline state (frozen at a given save point) are no
longer editable.
If the Document resides in a different Project, the Project containing the current Collection
appears in yellow above the Collection name.
Note
If the Document's HEAD is part of the Collection, if you click x you're taken out of the Collection
and a notification appears in the Document to remind you.
Warning
Any changes you make to a Document outside the Collection context will also be included in the
Collection's version of the Document.
3. (Optional) Click the Collection bar in Navigation to return to the Collection's detail screen.
4. Before you edit the Document as you normally would in the Document Editor read the following:
What makes Collection Documents different:
While working with Documents in the Collection context, some actions that are normally
available when Working with Documents are disabled.
• Only the Document, Tree and Table views are available for Documents in the Collection
context.
• The HEAD revision of a Document is only allowed in a single Collection.
(If you try and set a Collection Document to the HEAD revision in another Collection you'll receive
a warning.)
5. Before you add links between Work Items or Documents, read the following:
By default, links that lead outside a Collection are not visible in the Collection context.
This includes:
• Links in the title of the Work Item Editor, and the Linked Work Items section.
• The Work Item Properties sidebar (And the Edit Links section within it.)
• When links are shown as a table column.
Tip
Administrators can make links that lead outside the Collection visible if they wish.
(Either way, you can still add/remove in-collection Work Item links and not break or lose any hidden
Work Item links.)
Because Collections keep links to associated Documents or Work Items within the Collection context by
default, if a user tries to link to Work Items that fall outside the Collection context (via a Document, New
Work Item, or a table of Work Items), they receive the following:
• Links to specific Work Item revisions (pinned links) cannot be created when working in the Collection
context.
• If these pinned links already exist, they are considered valid if the revision corresponds to the revision of
the target Work Item in the Collection.
• A consistency check will not report on these pinned links if they point to the correct revision.
(If they don't point to the correct revision, they will be reported as invalid.)
• If the revision of the target Work Item in the Collection changes (for example, by changing the baseline
of the Document in the Collection), then these pinned links can easily become invalid.
This is where Collections shine. Unlike a Project Baseline where all artifacts are frozen at a set point,
Collections let you link to Work Items in Documents within the Collection that are in different stages of
development. ( Revisions).
Note
If you look at the HEAD revision of a Work Item, the link appears in the Linked Work Items section
but you won't see the revision number.
(That's because revision links are managed within the Collection context.)
Note
Suspect warnings are applied to all Work Items that link to the item being changed in their HEAD
revision.
(Work Items outside a Collection get a Suspect link, even though they are not displayed in the
parent Work Item.)
Collection Baselines
Related Topics
Collection Baselines place a marker in a Collection's history so that you can always refer back to
the Collection's state at important milestones. When you open a Document within the Collection
Baseline context, it's highlighted in navigation.
Procedure
4. Enter the baseline's Name (required) and a Description (optional) and click Create.
A Baseline successfully created message appears.
5. Click OK to open to the Collection in the Baselined context or Continue in HEAD to open the
most recent version.
If you click OK, a green button appears to remind you that you're in the Collection's baseline context.
Tip
Click on the green button view to the Collection baseline's details.
Note
Suspect warnings are applied to all Work Items that link to the item being changed in their
HEAD revision.
(Work Items outside a Collection get a Suspect link, even though they are not displayed in
the parent Work Item.)
Reuse Collections
When you Reuse a Collection a new Collection is created with references to the same content as the
source Collection.
(Selected source Collection Documents are frozen in the new Collection as they were when the Reuse
was done.)
• You can Reuse any Collection. (Including Closed Collections or a Collection Baseline.)
• You can Preview a Collection before you create it.
• While previewing a Collection, you can edit before you create it.
(This does not affect the source Collection.)
Procedure
3. Select the Project that you want the new Collection to be placed in.
(Only the projects that you have permission to create Collections for are available, and the project
you're currently in is selected by default.)
4. Click Preview.
Here you can review or add/remove Document references, change the Name or add a new
Description.
Note
Documents that were in the HEAD revision in the Collection that you reused are assigned a revision
number and frozen in the newly created Collection.
If you selected another Project to create the new Collection in, a Project field appears in the
Collection's details.
(The Reuse From field is entered automatically and can only be edited from the API.)
Related Topics
Close/Reopen a Collection
When a Collection is closed it can be considered baselined, along with all the Documents it contains.
Note
Administrators can define permissions that only allow certain users to Close or Reopen a Collection. If
you receive a message saying that you lack the required permissions, contact your administrator.
Close a Collection
Procedure
Note
This ensures that all Documents in the Collection have a set save point and won't include any
changes from other users currently working in the HEAD revision.
Tip
Not sure what Revision number or Baseline you need? Click the Document History link to
view all available options.
d. Repeat this process until all Documents in the Collection are set to a Baseline or Revision.
e. Select a Collection from the list, click then click Close again.
4. Click OK when the confirmation dialog box below appears.
Results
• A Closed On date appears in the table of Collections and [Closed] appears beside the Collection on its
details screen.
• Users can no longer edit the Collection's Description or the versions of the Documents it contains.
Reopen a Collection
Procedure
2. Select the Collection that you want to reopen from the table.
The Collection’s details appear below the table.
4. Click OK.
The Collection is reopened.
Pages are mostly what the name implies: web pages. However, they are only accessible to users who are
logged in to your Polarion system. Pages differ from Documents in that they do not contain Work Items
like requirements and test cases. However, Pages can show information about Work Items and other
artifacts in your projects and repository.
When you create a new Page, you can choose one of the following:
• LiveReport Page: A Page with a layout for a report with charts that retrieve, aggregate, and/or format
Work Item and other project data. You build these pages visually using a set of user-configurable
charting and other Widgets, and the rich-text formatting tools provided in the Page Designer.
• Info Page: A Page with a layout for free-form textual information, such as guidelines or internal
documentation. You build these pages using the rich-text editing tools provided in the Page Designer.
Images and tables are supported.
The main difference in these types is in the page layout. You can use Widgets in both types. Some
page features, such as the ability to extend Widgets with scripting or create reports, may be limited or
unavailable with some licenses.
When creating a new Page, the Classic Wiki Page option is also offered. These pages use the product's
original Wiki technology. It is recommended that you use LiveReport and Info Pages for new reports and
informational pages. For information on working with existing Classic Wiki Pages, see Using Classic Wiki.
Page Basics
The following main features and tasks are common to both types of Pages (LiveReport and Info). For
information specific to LiveReport Pages, see Build Reports.
The ability to create new Pages is controlled by user permissions settings in global and project
Administration. You must be granted Permission to CREATE NEW and Permission to MODIFY
for Pages in all projects in which you want to create new Pages.
Tip
When hovering over the Smart Title of a Page in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Page link with its Title as the link's label.
Pages exist within Spaces. You can create new Pages in any Space. There are several access points where
you can begin creating a new Page:
Procedure
1. On the Index page of any Space: Click the icon on the toolbar. (Tooltip: Create New)
3. Documents and Pages toolbar. Select this topic in Navigation, and then click on the icon
on the page toolbar.
Tip
Administrators can also configure Quick Create so users can create a Page right from the Navigation
Header.
Procedure
The ability to view Pages is controlled by user permissions settings in global and project Administration.
You must be granted Permission to READ for Pages in all projects in which you want to view Pages.
You can access existing Pages in two ways: browse or search. These work the same way for Pages as for
other types of content.
Tip
When hovering over the Smart Title of a Page in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Page link with its Title as the link's label.
You can browse for Pages in Navigation. Expand the Documents and Pages node, then expand the
node of any space. The Documents and Pages in the space are listed in alphabetical order and the content
type is indicated by the icons (see the Create New dialog).
If there are too many items to show in Navigation, a message appears in the panel under the space name.
You can either use Search or click on the message to load the space Index page, where you can browse the
Pages and Documents in the selected space.
The Search field of Navigation enables you to search your project or your entire portal for all types of
content, including Pages. For more information, see Search the Portal.
Delete Pages
The ability to delete Pages is controlled by user permissions settings in global and project Administration.
You must be granted Permission to DELETE for Pages in all projects from which you want to delete
Pages.
Procedure
1. Locate the Page by browsing or searching to determine the space where it is stored.
2. Open the space Index page, expand the space name in Navigation, and click Index. If you see a
message that there are too many items to show, click to message to load the space Index page.
3. In the space Index page, check the box on the row of all Pages you want to delete, and click Delete.
Edit Pages
Modify a Page
The ability to edit Pages is controlled by user permissions settings in global and project Administration.
You must be granted Permission to MODIFY for Pages in all projects in which you want to edit Pages. This
Procedure
1. Locate the page using browse or search, and open it for viewing.
2. At the top of the page, click Expand Tools.
3. On the Page toolbar, click Edit to open the Page Designer.
A Page is composed of one or more regions. Regions are simply containers for Page content. You can
modify the default layout of a Page to have whatever regions you need to show your content the way you
want it. You can select a Layout as well as add, remove, split or resize regions.
Select a layout
• Info Page has one region occupying the full width of the Page.
• LiveReport Page has three regions: one occupying the full width of the Page, and two occupying half the
width of the page.
When you first create a new page, you may want a layout different from the default. Several pre-defined
Page layouts are available, which may provide the layout you want, or at least a good starting point for
your custom layout. You can also apply one of the pre-defined layouts to an existing page. The Page
content is preserved, but it may not appear where you want it in the changed layout. You can either copy
content to a different region, or use the Undo button to revert the change. (Redo is available as well.)
You can access the pre-defined layout selectors in the Layout section of the Page Properties sidebar. The
options are:
• Three regions: Top one at 100% of page width, two below at 75% and 25% of page width.
• Three regions: Top one at 100% of page width, two below at 50% of page width.
• Three regions: Top one at 100% of page width, three below at approximately 33% of page width.
• One region at 100% of page width.
You can also specify the minimum width of the Page in this sidebar. The width is in pixels, and the default
value is 1000. In view mode in a browser, it sets the minimum width of the Page. If there is some wide
content such as an image that cannot be scaled, this setting can increase minimum Page width so that the
content is completely visible in the parent region.
In PDF export, the Minimal Width value is used to define page width of the PDF document, providing the
possibility to preserve the layout. If wide content is included in an insufficiently wide page, it will be scaled
(zoomed out).
You can add a region to the page by placing a new one, or splitting an existing one, using the following
commands on the header of an existing region:
• Add Region Above: Adds a new region above the current region.
• Add Region Below: Adds a new region below the current region.
• Split Region: Splits the current region into two, moving the current region, including its content, to the
left and adding a new empty region to the right. Content of the original region may be scaled to fit the
changed width.
You can remove a region from the page using the Remove Region command on the drop-down menu of
the region's header.
Resize a region
If you have multiple regions next to each other in a column-like arrangement, you can resize them
horizontally by dragged the separator that appears in the space between the regions. Vertical size of
regions is determined by their content and cannot be changed manually.
Format text
Pages support basic rich-text formatting. If you have used a desktop or online word processing application,
the rich text tools of the Page Designer will seem quite familiar and work as you expect. If you have worked
with Documents, the same text formatting tools are present on the toolbar when editing a Page. The
following text formatting options are available:
System Administrators can change the ordered list style by adding or editing the
com.siemens.polarion.document.listStyle= X property in the polarion.properties file.
(Where “X” can be a series of up to 9 values representing each tier of a Multilevel List.)
Then, the ordered lists only contain numeric values like the example below:
2. Choose Show Sidebar Page Properties. The Page Properties sidebar appears.
3. In the Outline Numbering section, click ON.
4. Save the Page.
Outline numbers for headings are not visible in the Page Designer while editing a Page. They appear only
in view mode. Outline numbers are only applied to headings specified in the user interface. Headings
created via a script (using, for example, <H2>) will not have outline numbering applied.
Copying and pasting text within a Page is similar to other applications. There are several things applicable
with Pages that may be worthwhile to note:
• Within the same page you can copy and paste the following:
◦ Block of text to the same or a different region
◦ Chart or table widget to the same or a different region
◦ Links to a different region (relative links remain relative)
◦ Region to another region
• Between different Pages you can copy and paste:
◦ Block of text
◦ Chart or table widgets
◦ Links: Relative links remain relative.
◦ Region
• From an external application to a Page you can copy and paste:
◦ Block of text
◦ Links
• From a Page to an external application you can copy and paste:
◦ Block of text
◦ Links
◦ Widgets: If text and widget is pasted to an external page, only text is pasted.
Note
Copying Work Items within the Same Document
When On-demand Work Item Loading is turned ON, make sure that all the Work Items you wish to
copy have finished loading before pasting them somewhere else within the same document.
(This limitation does not apply when copying them to a different document.)
Insert content
In addition to text, you can insert several other types of content into any region of a Page:
• Images
• Attachments
• Diagrams
• Formulas
• Tables
• Links
• Table of Contents
• Widgets
The button is available on the toolbars found on Pages, LiveDocs and rich text Work Item fields. It
launches the Insert Image or Attachment Preview dialog.
The dialog initially displays previews of images and attachments that are already attached.
It's also where new images or attachments with previews can be added.
Caution
You can insert Scalable Vector Graphics (SVGs) into LiveDocs or rich text Work Item fields (like the
Description field), but you must also attach a .png file with the same name if you want to export
the Document to PDF or Microsoft Word. (If you don't, the following warning appears instead of your
image in the exported content.)
If you resize a diagram or SVG image in Polarion and change the aspect ratio, it is malformed when
exported to PDF.
Procedure
When you have images or attachments in both a LiveDoc and Work Item and the Insert Image or
Attachment Preview dialog is opened inside a Work Item, both sections appear.
When you have images or attachments in both a LiveDoc and Work Item and the Insert Image or
Attachment Preview dialog is opened from inside the LiveDoc, only the Document's images and
attachments appear.
Note
Hover over an image or attachment preview in the Insert Image or Attachment Preview dialog to
see its file name and title (if any).
Note
Unsupported characters in attachment names will either:
• Prompt an error message.
• Be replaced with _ (underscores).
4. If items with the same file names already exist, you will be prompted with the following message:
(When uploading a file with the same name as one already saved within a Work Item, the Revert
option is not available and both files are saved with the same name.)
5. Click Revert to revert to the original files. Click Insert to add the ones you selected and confirm the
overwrite.
6. Selected items are added and their previews appear in the Rich Page, LiveDoc, or Work Item.
Images and Visio diagrams with a width larger than 750px are resized, with their aspect ratio
maintained, to a width of 750px.
(The width of the page when inserted into a Live Document.)
The previews of common document formats (like .docx, .pdf, .xlsx, and .txt) are resized to a width of
250px and take up one third of a Live Document page's width.
For less common file types, where previews cannot be generated, an icon is added instead. (See the
image below.)
The Attachments are added to the Attachments sidebar and their previews are also visible when the
document is Exported to PDF.
PDF output:
You cannot insert a Polarion diagram itself (the .mxg file) via the Insert Image or Attachment Preview
dialog box. Instead a preview of the diagram will be added and the original .mxg file will be listed in the
Attachments sidebar.
See the diagram section to create and edit diagrams directly into a Document, Page or Work Item text
field.
Fit To Width: Resizes the image width to the document width. (Not available for Work Item Rich Text
fields.)
Keep Aspect Ratio: Active by default. Ensures that the height and width maintain the same ratio when
resized.
• For a full screen preview of resized images or attachment previews in Edit mode, click on the image
or attachment, and then click Preview.
(Or double-click on the image or attachment preview.)
• When not in Edit mode, a single click will launch a full screen preview.
• Click ESC to exit the full screen preview screen.
View: Launches the object in its own browser window or the default program configured by the OS to
open the selected file type.
Update: Upload an updated version of the previewed object. (Disabled for read-only documents or for
users with read-only permissions.)
Close: Closes the preview window. (ESC also closes the window.)
Inserted images, diagrams, or files become attachments of the Page, and remain attached even if visually
removed from the Page content. To delete an image attachment completely, see Delete an attachment.
Note
Adding URL links to images is not supported.
Pasting images
Ctrl+V or Command+V can be used for images within the document, but if they are used for an image in a
Work Item within the document, its thumbnail will not appear in the Attachments sidebar.
Rich pages, Live documents and Work Item rich text fields can have almost any type of file as an
attachment. Once an attachment has been uploaded, a link to it or a preview of it can be inserted directly
into the document. Or it can simply be appended to the document by leaving it in the Attachments
section of the Attachments sidebar.
Procedure
Procedure
See Add a new image or attachment for details on how images and attachment previews appear.
Suppose you have a PDF file attached to a Page, and at some point you find there is an updated version
of the same document, with changed content. You can upload the updated version to replace the existing
attachment. The uploaded file must be of the same type and have exactly the same file name and
extension.
Procedure
4. Click the Update icon. Your operating system's file selection dialog appears.
5. Select the file in your local file system, and click the button that confirms the selection. Wait while the
file uploads.
6. When the upload is complete, save the page to finish updating the attachment. It is now available to
users viewing the page.
Delete an attachment
If you find some attachment is outdated or no longer needed, you can delete it from the Attachments
sidebar. Keep in mind that if you have any links to the attachment file, you need to remove them from the
Page content.
Procedure
1. Locate the desired Page by browsing or searching, and open it for editing in the Page Designer.
2. On the Page Designer toolbar, click the Show Sidebar button and select Attachments to reveal the
Attachments sidebar.
3. Locate the attachment you want to update. If there are many attachments or some attachments are
hidden, use the search field of the sidebar.
4. Hover your pointer over the attachment you want to update. It highlights and exposes several icons.
Caution
Remember that any links to the deleted file will not work, so be sure to review the page content.
5. Click the (Delete) icon. The attachment no longer appears in the Attachments sidebar.
6. Save the page to finalize deletion of the attachment.
Page comments
You can comment and reply to comments on LiveReports or Info Pages to collaborate and review any
changes with your colleagues.
Note
• Administrators must Set Page comment permissions and notifications before users can comment
on Pages.
Unlike Document comments, where comments appear within the Document, Page comments
are visible and managed exclusively in the Comment Sidebar.
Procedure
1. Click Expand Tools at the top of the Page and select one of the following:
a. Add Comment
b. then Comments
2. Here you can do one of the following depending on what comments are in the sidebar and your
permission settings.
(If you click Add Comment you do not need to click Add Comment.)
• Click then select / deselect Show Resolved Comments to view / hide resolved comments.
• When you Show Resolved Comments, you have the option to Reopen them.
Note
You can only Resolve or Reopen top-level comments. (When you do, their child-level
comments are also resolved or reopened.)
• Click to delete a comment. If you delete a top-level comment all its child-level comments are
also deleted.
(You can delete both resolved and unresolved comments. )
3. Click Save Comment at the bottom of the sidebar, or on Page toolbar if you are in Edit mode.
• also saves any other updates done on the Page.
• Save Comment only saves comment updates.
Insufficient permissions
If you do not have the necessary permissions to add or manage comments the Add comment buttons are
grayed out.
Note
You can still view existing comments in the Comment Sidebar but they are read-only.
Comments in History and Baselines are read-only and are filtered by their revisions.
Example
If you add a Page comment and save but then add additional child-level comments and save, two
revisions are created. If you view the revision you added the parent comment in, you will not see the
newer child comments.
Administrators configure Pages so that targeted users (like the author of the Page or a comment) are
notified via email every time a change is made to the Page, or someone has replied to a comment that
they wrote.
Insert tables
The Insert Table button on the Page Designer toolbar launches a dialog in which you can specify the basic
properties of the new table such as number of rows and columns, width, alignments, border, and header.
Tables can be inserted into any region of a Page. Locate the insertion cursor in the region at the point
where you want to insert a table, and then invoke Insert Table.
Note
The maximum width of tables is 1280px when the width is configured as a percentage value. If the
width of a table is configured in pixels, then there is no limit.
After a table has been inserted, whenever your cursor is in a table cell, the Table menu is available on the
Page Designer toolbar. It contains a number of items that enable you to modify the table. You can:
If you split a region that contains tables, the tables will be automatically resized. You may want to review
them and make adjustments such as resizing the columns. You can resize columns by dragging a vertical
border to the left or right.
Insert links
You can insert text hyperlinks into any region of a Page. The Insert Link button on the Page Designer
toolbar launches a dialog in which you can specify the target URL, and optionally the link text of the
hyperlink. If you don't change the Label field, the URL appears as the link text.
• Links to Polarion items (represented by the item type icon and its ID/Title).
• Internal portal links, represented by internal URL link text.
• External links, represented as external URL link text.
Place the insertion cursor at the point in the region where you want to create a link, and click Insert Link.
Tip
You can also create a link by pasting a URL into the Page text. Be sure to leave a space before and after
the URL, otherwise it is not recognized as a link. The link text will include all characters in the URL. After
a link is created, the link itself can be copied and pasted. A pasted link is processed and recognized
according whether it is a link to a Polarion item, an internal portal link, or an external link.
You can insert a automated table of contents into a Page. Although it is possible to insert this into any
place in any region of a Page, the most common practice is to insert it at the beginning of the topmost
region. A Page only accepts one table of contents. If you try to insert another one, you see an error
message.
Table of contents entries do not appear in the Page Designer, even after you save changes. They are
generated only after closing the designer and returning to view mode. If the Page does not contain any
Table of contents elements, a message to that affect appears when the page is viewed. The TOC cannot be
copied/pasted.
You can delete the Table of contents from a Page by clicking on it in the Page Designer, and pressing your
keyboard's Delete key.
Insert a Widget
Note
Users of a Polarion Pro license cannot insert Widgets.
Widgets retrieve and format project data from your Polarion portal for reporting purposes. Normally, you
use them only in LiveReport type pages, but it is possible to use them in any page of either type. If you
decide you want to show some chart on project Work Items in an Info Pages, you can.
The Widgets sidebar is shown by default when you are editing any Page, and you can optionally insert
Widgets into any region. The distinction between Info and LiveReport pages is made purely to generalize
different use cases. The page types use different layout templates but are otherwise the same.
You can set yourself (or another user) as a Watcher for a Page or Work Item. Watchers receive an email
notification when the watched artifact is updated or removed.
Tip
Administrators can configure the Events and Targets for Pages.
Procedure
Note
You cannot Watch the Home pages of Spaces.
You can add another user as a Watcher to any Page that you have WRITE access for.
Procedure
4. Start typing the name of the user to set as a Watcher. (Potential matches begin appearing.)
You can view, add or remove Watchers for a Page that you have WRITE access for.
Procedure
4. Do the following:
• Enter the name of a Watcher you want to add in the Add Watchers field and select them when
you find them.
• Click beside an existing Watcher to remove them.
5. Click Apply when you are done.
Page Watchlist
You can view and remove the LiveReports or Info Pages you are currently Watching in your
Watchlist:
Note
• The Watched artifacts are user specific.
(You can only see artifacts that you are Watching. You cannot see the Watches of other users, even if
you are a System Administrator.)
• You must have the READ permission for Pages to view them in the Rich Pages section.
If your READ permission is revoked, the Rich Pages section appears empty.
(Your Watchlist also displays the Work Items you are currently watching.)
Under the Watches heading you can view the current scope ( Project or Global) and your watches
are listed accordingly.
This section lists the number of Work Items you are currently Watching.
The number changes dynamically when you add or remove Work Item Watches.
Click Open in Table , to view the Work Items you are watching in Table view. (In a new browser
tab.)
Tip
• Click on a Page's Title to navigate directly to it.
• Watched Pages listed under the Rich Pages section for the Default Repository or Project
Group contexts include the Project column. The Project column is hidden if you're viewing the
Watchlist in a specific Project.
Scope of Watches
The Work Items and Rich Pages you are Watching are filtered based upon the following:
• If you open the Watches window from a specific Project, for example E-Library, then only the
currently Watched Work Items and Rich Pages of the E-Library Project are listed.
If you open the Watches window from a Project Group of multiple Projects, then only the currently
Watched Work Items and Pages of those Projects are listed.
If you open the Watches page from the Default Repository context, then:
• All Watched Work Items and Pages across all Projects are listed.
• All Watched Work Items and Pages of the Default Repository itself are listed.
You can trigger email notifications for any updates to Pages ( LiveReports or Info Pages).
(They notify configured users of text content or formatting changes and changes to script blocks.)
Tip
Notifications only contain changes to the affected sections. (Not the entire Page.)
The image above displays the default configuration. It states that the email notification is sent to:
• The author of the Page (the person who created the Page).
• Watchers of the Page (people who Watched the Rich Page by clicking Expand Tools Watch.
The email notification highlights any text that was added to the Page in green.
• Font changes
• Font size updates
• Font styling changes (bold/italics/color/highlight)
• Increases/decreases in text indents
• Text alignment updates (left, center, right)
If a word in a sentence changes, the removed text is highlighted in red, and its replacement is highlighted
in green:
Note
• New links or cross-references added to the Rich Page are highlighted in green. (Red if they are
removed.)
• If an image preview is added as an attachment, then it is also highlighted in green. If removed, it is
highlighted in red. (The actual image preview does not appear in the notification.)
If someone adds or removes an empty region, the notification email lets you know that the Rich Page
content was updated, but you must compare revisions to see where the empty section was added/
removed.
If someone adds or removes an empty widget (for example an inline script), the specific region is
highlighted in green or red respectively in the email notification.
Widget script changes are also highlighted in green or red if something was added or removed.
The example below shows that a script block script was changed (a new paragraph was added):
This applies to any widget, for example, a pie chart. If you change the title of an existing pie chart, then
the change in the script is highlighted accordingly, and the user gets notified.
In the following example, the Title of the pie chart is changed from Chart Title to Task:
When you click Save, configured users get the following email:
Note
Changes appear in the notification in the same sequential order as they do in the Rich Page.
Page History
As with other artifacts, Polarion automatically tracks every change made to Pages and maintains a
complete change history. Pages are included in Project Baselines.
Procedure
You can Print a Page or Export to PDF, but before you do you might want to hide some content.
Note
Embedded image or attachment previews are preserved when a document is exported to PDF or
printed.
To exclude any region on a Page from appearing in PDF or printed output, you must have permission to
modify Pages in the project.
Procedure
Tip
on LiveReport Pages, don't confuse region headers (light gray) with Widget headers (light blue, light
yellow on hover). You can only hide the region that contains Widgets, not the Widgets themselves.
Procedure
Note
If you do not click Configure, the Document will use header and footer configurations set on the
project or global level by your administrator.
6. Click Export.
Tip
You can change the settings and quickly export the same Document again until you close the
dialog box.
7. Save or open the exported PDF. (Options will vary depending on your browser and operating system's
PDF settings.)
Print a Page
Procedure
You can download a Page as a ZIP archive. You can import a previously downloaded Page to create a new,
duplicate Page. Reusing Pages this way can be useful if, for example, you have built a report and need
a similar report in a different project, or in the same or a different space in the same project. You can
download the completed Page, import the downloaded ZIP file to any project and space to which you have
access, and then modify the page as needed.
Download a Page
Procedure
2. At the top of the Page, click Expand Tools. The page toolbar appears.
3. Click the (actions) icon, and choose Download on the drop-down menu.
4. Select the location where you want to store the Page archive. The suggested archive file name
includes the revision number of the page you are downloading.
Procedure
1. Open the project into which you want to import the Page archive to create a new Page.
2. Open the Index page of any space in the project. It will save a little effort if you open the Index page
of the destination space.
3. On the Index page toolbar, click the button to launch the Create New dialog.
4. In the Import section of the dialog, click Page Archive. The Import Page dialog appears.
5. In the dialog, specify the Title and Name of the new Page to be created from the imported Page
archive. The Name (ID) must be unique to the space into which you are importing. (This is especially
important if you are importing to the same project and space from which the page archive was
downloaded.)
6. If you want to change the target space, select the desired one in the Space field. (The current space is
selected by default.)
7. Click Choose File, and then browse your local system to select the Page archive file you want to
import. (This file must be one previously downloaded from an existing Page).
8. Click OK to complete the import operation, and create a new Page from the imported Page archive.
You can open the page in the Page Designer and modify it as needed.
Build reports
About reports
One of Polarion's major benefits is its ability to track actual progress of work on various artifacts of projects
such as requirements, test cases, test runs, and change requests. Data is generated as people work day to
day changing the status of different Work Items, executing tests, and creating plans.
Project stakeholders can browse various artifacts and gain a good understanding of the actual progress of
the project.
Pages in Polarion include special tools such as Widgets and interactive reports to support tracking based
on the actual progress of work and changing data. Polarion's LiveReport Pages make it easy to use the
Widgets to build robust reports visually without scripting or programming skills. Developers and other
advanced users can use custom scripting with LiveReport Pages to create highly custom reports.
Introduction to Widgets
Tip
If you don't know how to Edit Pages, you should read up on that first before diving into Widgets.
Widgets are the building blocks of reports. You insert Widgets into Pages and set their parameters to make
them show the information you want in the report. You can place Widgets into any region in a Page.
Widgets, combined with the layout and rich text editing features of Pages, enable you to build useful and
good-looking reports that users can print or export to PDF.
When you place a Widget into a page, you see some graphical rendering of it but no data. In order to
make the Widget perform its intended function, you must edit its parameters in the Parameters sidebar.
Each Widget has its own set of Parameters that work together to retrieve and render information. There are
several commonly used Widgets that are best illustrated in an example of a simple table of project Work
Items. Many of the parameters are applicable for charts as well.
• Chart Widgets retrieve and display project data as some type of chart.
• Utility widgets provide data tables, object counts, and interactivity for report users.
• Scripting widgets provide programmers the means to implement custom functionality in reports.
The Widgets sidebar is organized into several categories containing groups of related Widgets - scripting,
for example. (The Categories can be customized by a developer.)
Tip
You can see a brief description of each of the available Widgets in the Widgets sidebar by hovering your
pointer over each one.
Insert a Widget
Procedure
1. Select your Report, click Expand Tools at the top and click Edit.
2. Click on the top right and click Widgets. The Widget sidebar appears.
3. Place the insertion cursor inside a region at the point where you want to insert the Widget.
4. In the sidebar, click on the Widget you want placed in the Page. The Widget is rendered visually in
the Page and selected for editing. The Parameters sidebar opens, replacing the Widgets sidebar and
displaying the parameters of the Widget you just added.
5. After placing a Widget into a Page, you can do one of the following:
• Configure its parameters.
• Place other Widgets to complete the layout of your report, and then configure Widget parameters
later.
• Add Page Parameters that can help make some widgets more interactive.
You can insert Widgets in any region of a Page. When developing a new report, it is usually best practice
to construct the Page layout first (see Modify Page Layout).
If you decide to complete the layout first, close the Parameters sidebar. Then reopen the Widgets
sidebar from the Show Sidebar button on the Page toolbar.
Edit a Widget
You can edit Widget parameters after completing the report layout, or you may find at some point that you
need to modify the parameters of an existing Widget.
Procedure
1. Select your Report, click Expand Tools at the top and click Edit.
2. In the Page Designer, click the Widget's blue header. The Parameters sidebar appears with the
parameters for the selected Widget and the Widget's header turns yellow.
3. Edit the parameters and click Apply.
You can explicitly set the height and width of chart Widgets to achieve a desired page layout. The
Advanced section of the Widget parameters contains Height and Width fields, which you can set to
achieve the desired layout of a chart on a Page. Chart Widgets are block type Widgets (as opposed to
in-line type), and the chart rendered inside them is always centered within the block.
Note
These parameters are also accessible to developers via the Polarion API.
After a Widget is placed into a Page region, you may want to insert another widget, or insert other content
before or after that Widget. You need to use the special menu commands found on the header of each
widget.
1. With the page open for editing in the Page Designer, click on the Actions icon on the Widget's
header.
2. In the drop-down menu, select Insert Paragraph Above or Insert Paragraph Below.
3. Insert another Widget or other content in the added paragraph space.
Note
Users of Polarion PRO license can insert paragraphs above or below Widgets, but cannot insert new
Widgets.
Copy a Widget
You can optionally copy a Widget and paste it to a different region or Page. This can save time if you need
several Widgets of the same type, but with minor differences in the parameters. You can just tweak the
parameters in the pasted Widget.
You can optionally copy the source code of a Widget you have inserted and configured visually. This can be
useful for developers who are writing extended or custom Widgets or developing custom scripts for use in
one of the scripting Widgets.
Procedure
1. With the Page open for editing in the Page Designer, click the Actions icon in the header of the
Widget you want to copy.
2. On the drop-down menu, choose Copy Widget.
If your browser has security restrictions that block it from direct programmatic access to your
clipboard, a dialog appears prompting you to use the Copy keyboard shortcut. If you see this dialog,
you can always just select the Widget in the Page and press your Copy shortcut.
3. Place the insertion cursor in the region where you want to paste the copied Widget
4. Press your Paste keyboard shortcut (Ctrl+V or Command+V).
Procedure
1. With the Page open for editing in the Page Designer, click the Actions icon in the header of the
Widget you want to copy.
2. On the drop-down menu, choose Copy Widget Source Code.
If your browser has security restrictions that block it from direct programmatic access to your
clipboard, a dialog containing the source code appears, which prompts you to press your Copy
shortcut to copy the code from the dialog. Otherwise, the source code is silently copied to your
clipboard.
Delete a Widget
Procedure
1. With the Page open for editing in the Page Designer, click on the header of the Widget you want to
delete.
2. Press the Delete key on your keyboard.
Tip
You can also use the Delete command on the Actions menu of the Widget's header.
Add a Widget
When you place a Widget into a page, you see some graphical rendering of it, but no data. In order to
make the Widget perform its intended function, you must edit its parameters in the Parameters sidebar.
Each Widget has its own set of Parameters that work together to retrieve and render information. There
are several commonly used ones which are best illustrated in an example of a simple table of project Work
Items. Many of the parameters are applicable for charts as well.
Procedure
1. Choose a LiveReport or Info page from a Space under the Documents & Pages topic.
2. Click Expand Tools at the top of the page.
3. Click Edit.
4. Click in the page box where you want to insert the widget.
Procedure
Kanban board
You can create a drag and drop Kanban style board for Work Items on LiveReport, Info Pages and
Plans. The number of columns (workflow states), the type of Work Items to include, and the board's
appearance are all defined in the Kanban Board: Parameters sidebar.
The properties of a Swimlane (parent Work Items) and their children (Cards) can be viewed and modified
by clicking on their whitespace.
Note
The 206 at the top of the first column is the total number of open items. You can configure how many
items that you want to be visible (Showing 5/206) in the column.
Procedure
1. Select a LiveReport, Info Page, or a Plan and launch the Widgets sidebar.
a. Choose a LiveReport or Info page from a Space under the Documents & Pages
topic.
c. Click Edit.
• For a Plan:
3. Select the Work Items or Planning tab under the Widgets sidebar.
4. Click on the Kanban Board icon. The Kanban Board: Parameters sidebar opens on the right.
5. In the Scope field, select a Project, Project Group, or the whole Repository.
6. Select a Query Type. (If you are unsure what kind of query type to use, just leave it on Lucene. You
will be able to build a query graphically in the steps that follow.)
7. Select a Work Item Type.
• To add a single Work Item type to the board, you can select it from the Type drop-down list.
• To select more than one Work Item type, leave the default Work Item selected.
8. Use the Query field to define the Work Items you want added to your Kanban board.
a. If you're familiar with Polarion's advanced command-line query syntax, you can paste your
query directly into the field.
b. Click to define what items to include graphically.
c. Click a set of options to include and click . ( Click multiple times to add additional
criteria.)
In large projects, you can combine the command-line and graphical query options to really
fine-tune your selection.
9. Add a Title for the first status, for example Open, in the Columns section.
10. Click , choose a status item from the Available Items on the left, and click . (You can add
more than one.)
12. (Optional) Click under Sort By, and select how the Work Items are sorted and the direction
that they should be sorted in. (Multi-selection works here.)
15. Click Add Column and repeat steps 10 through 14 for each workflow status.
16. (Optional) Click on a card to launch Work Item Properties Sidebar and add fields that you want to
appear.
• As a report editor: (Edit mode):
a. Click under Work Item Properties Sidebar Fields to add any fields that you want to
appear under the Work Item Properties Sidebar. (Launched when a Kanban, Table or Work
Items Board widget item is clicked. Multi-selection works here.)
b. Select a field on the left, click , and click OK when you've finished adding the fields you
want to include.
c. Click a card and the selected fields appear in the Work Item Properties Sidebar.
• As a user:
Anyone who clicks on an item in a widget that supports the Work Item Properties Sidebar.
a. Click on a Card, Swimlane, or table item.
The Work Item Properties Sidebar appears on the right.
b. Click the icon on the top right and click Select Fields.
Selected items can only be added or The selected fields will be your personal,
removed when the report is in Edit mode. default fields for all widgets that support
the Work Items Properties sidebar with the
currently selected Project.
c. Select a field on the left, click , and then click Set as Personal when you've finished adding
the fields you want to include.
Note
Work Item Properties Sidebar fields:
◦ Grayed out fields can only be removed when the report is in Edit mode
◦ The fields will appear in the Work Item Properties Sidebar for all Kanban, Table and
Work Items Board widgets.
◦ Fields added by a user (when not in Edit mode), will only be visible to them.
◦ Add fields in Edit mode above if you'd like other users to also view them by default.
◦ The added fields will only appear for the selected Work Item type ( ) and
Project.
d. The fields will be added to the Work Item Properties Sidebar of all the Kanban, Table and
Work Items Board widgets in the selected project.
17. Click Apply or follow the instructions in the following Customize the Kanban Board's Appearance
section to change the board's appearance.
You can customize the appearance of the cards by adding custom velocity snippets. You can change the
color of the card, remove the status border color, show different Work Item fields, re-arrange the fields
already rendered, and more. The custom Velocity scripts will be rendered instead of the default java scripts.
Default velocity snippets are included with the widget under the Board Script and Card Script parameters
and are a great starting point. The sample scripts mimic the java rendered output that's provided out of the
box.
Procedure
Customization options:
• Board Script: Insert at the beginning of the board. Always use to add custom CSS styles and/or
JavaScript common for all your cards. This avoids needing to duplicate the scripts for each card.
Caution
The styles inserted in this script are applied to the whole page.
• Card Script: Defines the content that appears within the cards.
The Card Script Velocity script allows for the following additional objects:
◦ $workItem: The Work Item rendered in the card.
◦ $columnIndex: The column that the card is rendered on.
Tip
The Work Item Properties sidebar and the ability to drag and drop are still available when
customizations are enabled.
Procedure
2. Click on the top right of the board in Edit mode to open the Kanban Board: Parameters sidebar.
3. Click Advanced.
4. Define The maximum # of results per columns that appear.
Click the Showing #/# link on the bottom of a column to see the next list of items.
5. Click Yes to Enable Customization.
6. Click on Board Script. (For a full screen view of the script press F11 and Esc to exit full screen view.)
7. Change the background color of the card by adding background-color: #d0d2e0;
to .kanbanWorkItemDiv.
(#d0d2e0 can be replaced with any color you'd like.)
8. Change the gradient of a long title by changing the background property
in .kanbanWorkItemTitleGradientDiv to,
background: linear-gradient(to bottom, rgba(255, 255, 255, 0), #ccffff)
repeat scroll 0 0 rgba(0, 0, 0, 0);
9. Enable the Work Item Properties Sidebar by adding:
.polarion-sidebar-highlight .kanbanWorkItemDiv {
background-color: #fff9e8;
}
kanbanWorkItemDiv {
padding: 7px 3px 3px 7px;
box-sizing: border-box;
border-left: 5px solid;
border-right: 1px solid #EEEEEE;
border-top: 1px solid #EEEEEE;
border-bottom: 1px solid #EEEEEE;
border-radius: 5px;
position: relative;
background-color: #d0d2e0;
}
...
.kanbanWorkItemTitleGradientDiv {
bottom: 0px;
height: 12px;
left: 0;
position: absolute;
width: 100%;
display: inline-block;
background: linear-gradient(to bottom, rgba(255, 255, 255, 0),
#d0d2e0)
repeat scroll 0 0 rgba(0, 0, 0, 0);
filter: progid:DXImageTransform.Microsoft.gradient
(startColorstr='#00FFFFFF', endColorstr='#FFFFFFFF', GradientType=0);
}
...
.polarion-sidebar-highlight .kanbanWorkItemDiv {
background-color: #fff9e8;
}
...
You can customize what content appears within the cards in Card Script.
Procedure
2. Click on the top right of the board in Edit mode to open the Kanban Board: Parameters sidebar.
3. Click Advanced.
4. Click on Card Script. (For a full screen view of the script press F11 and Esc to exit full screen view.)
5. Paste the table text below between the <div class="kanbanWorkItemDiv" style="border-
left-color: $wiStatusColor;"> and <table class="kanbanWorkItemTable"> tags.
<table width="100%">
<tbody>
<tr>
<td class="kanbanWorkItemTitleDiv">
<div class="kanbanWorkItemTitleGradientDiv"></div>
<a href="$wiLink"
target="_top">$workItem.fields().title().render()</a>
</td>
#set($treeLink
=$transaction.context().createPortalLink().project("$wiProjectId").workI
tems().query("id:$workItem.getReference().id()").toEncodedRelativeUrl())
#set($suffix = '&tree_depth=2&tab=tree')
<td style="vertical-align: top;">
<a href="$treeLink$suffix" target="_blank">
<img style="float: right;" title="View Item in a Tree Structure" src="/
polarion/ria/images/details/treetable.gif"/>
</a>
</td>
</tr>
</tbody>
</table>
6. Click Apply.
A tree icon with a link to the card's Work Item in Tree view is added to the card.
The Work Item Properties sidebar and the ability to drag and drop are still available when customizations
are enabled, and you can always revert to the internal Java rendering by setting Enable Customization to
No.
Kanban FAQ
A simple but useful report element is a table of unresolved Work Items sorted by type, severity, and
current status, and showing several key fields such as ID, Title, Status, and Severity.
If you have the appropriate permissions, you can modify a Work Item's fields by clicking on it.
The fields that appear can be configured in the Table - Block: Parameters sidebar.
• For a Plan: Click on Customize Plan Report above the table widget.
• For LiveReport and Info Pages: Click on Expand Tools Edit above the
table widget.
c
t
W
o
r
k
I
t
e
m
P
r
o
p
e
r
t
i
e
s sideb
e
t
a
b
l
e
.
How the Work Items are sorted in the table. (Multi-selection works here.)
Note
The Work Item Properties sidebar Fields only work for Work Items.
See the Kanban Board section to learn how to define what fields appear and what widgets are affected.
The table will show a subset of all available project data, so it's necessary to set some parameters to
retrieve the desired data.
• Scope: Specify the scope of the data to be retrieved. The default is the current project, but you could
retrieve data from a different project from the one in which you are currently working, or from the entire
repository. In this example, the scope is the current project.
• Query Type: Select the query language to retrieve data. The full arsenal of Polarion's data retrieval
capabilities are available here, including Apache Lucene query language, SQL, or combinations of
Lucene and Velocity, or SQL and Velocity. For the purposes of an easy example, Lucene is used, as many
users are familiar with this type of query, and the Visual Query Builder is integrated in Widgets enabling
users who don't know a query language to build queries visually.
• Type: Specify what main artifact type is the basis for the data. You can select Work Items, Documents,
Collections, Plans, Test Runs, or Pages. You can further refine this by selecting one of the subtypes
defined for the different artifact types (if any).
If the artifact type is Work Item or Document, you can select the type in the list. For example, for
the Work Item artifact type, there might be Requirements, Test Cases, Issues, Tasks, and so forth.
The Document artifact type might have subtypes such as Requirements Specification or Risk Analysis.
The subtypes list varies according to the Scope. For example, Repository scope lists all Work Item and
Document types defined in the global configuration, whereas selecting a project limits the list to the
types defined for the selected project.
For this example, Work Item is selected, because the table must show Work Items.
• Query: Refine data shown in the table through a query. In this simple example, Lucene is selected as
the query type. For Lucene queries, the same Visual Query Builder tool you may already have used in
the Work Item Tracker is available. You can use it to add multiple visual query elements to the Query
to build queries ranging from ultra simple to very complex. For this simple example, only one element is
added: a query on the Resolution field, for a value of "unresolved".
• Columns: Specify the columns to show in the table, and their order, using the Select button under the
Columns field. The selection dialog is the same one you use to customize the Work Items table in the
Work Item Tracker. Columns in the table display Work Item fields, because Work Item is selected in the
Type parameter.
For this example, the ID, Title, Type, Status, and Severity fields are selected to appear as table columns.
Tip
What you can select to show in columns depends on the artifact type selected in Type. Work Items
have different items than Documents or Test Runs.
• Sort By: Specify how Work Items are sorted in the table.
◦ The specification of the example called for sorting by Type, Severity, and current Status.
◦ Sorting by Type first causes the different Work Item types to be grouped. So all Issues appear first,
followed by all Change Requests, Requirements, and finally Test Cases.
◦ So all Issues appear first, followed by all Change Requests, Requirements, and finally Test Cases.
Within those groups, the rows are sorted by Severity in Ascending order. Finally, the rows for a given
severity are sorted by the current Status of the individual Work Items.
◦ The field's Select button, leads to the same dialog that lets you select the fields to sort with, the sort
order (ascending/descending), and the order of the fields.
Note
Outline Numbering cannot be used with other sorting options and disables them if its selected.
• Work Item Properties Sidebar Fields: Select the fields that appear in the Work Item Properties
Sidebar.
• Show Top Rows: Expand the Advanced section of the sidebar to see this field. This can be an important
parameter if the table is potentially very large. The default is 50, meaning the table only shows the first
50 items matching the query, and displays a link that opens the Work Item Tracker in a new browser
tab and load all the marching Work Items.
Warning
Click the Apply button in the sidebar to update the visual rendering of the Widget in the Page Designer
after modifying parameters. This applies to all Widgets.
Users do not see any changes to the Page until you save changes you make in the Page Designer. After
the Page is saved, the report is live in the sense that the table reflects the status of the items in the project
as of the time the user loads the report page. Users can see any later changes in the data by refreshing the
page in their browser.
Transitions and Statuses are based on the configured Work Item's workflow.
If there are no additional workflow conditions or required fields, a Work Item is automatically saved when
dragged to a new state.
If a Work Item requires additional input, for example a Resolution, the Work Item Properties sidebar
automatically appears when the item is dragged to a new state.
See Customize the Work Item Properties sidebar and Work Item Properties sidebar for more
information.
Swimlane
The properties of a Swimlane (parent Work Items) and their children (Cards) can be viewed and modified
by clicking on their whitespace in the sidebar.
Select the Status options that appear in the column. Available options depend on what is defined in
the Work Item workflow. (Multi-selection works here.)
Define the sub task link roles: Is triggered by, Implements, Verifies, Has Parent and so on. (Multi-
selection works here.)
Work Items appear in compact form when in the selected Statuses. (Multi-selection works here.)
Fields visible in a Swim lane’s Work Item Properties sidebar. (Status or Severity by default.)
Fields visible in a Card's Work Item Properties sidebar. (Status / Severity by default.)
You can customize what fields appear in the Work Item Properties sidebar for your Work Items Board.
Procedure
• For a Plan: Click on Customize Plan Report above the table widget.
Select the Status options that appear in the column. Available options depend on what is defined in
the Work Item workflow. (Multi-selection works here.)
Define the sub task link roles: Is triggered by, Implements, Verifies, Has Parent and so on. (Multi-
selection works here.)
Work Items appear in compact form when in the selected Statuses. (Multi-selection works here.)
Fields visible in a Swim lane’s Work Item Properties sidebar. (Status or Severity by default.)
Fields visible in a Card's Work Item Properties sidebar. (Status / Severity by default.)
You can customize what fields appear in the Work Item Properties sidebar for your Work Items Board.
Procedure
• For a Plan: Click on Customize Plan Report above the table widget.
3. Select items from the Available Items box on the left and click .
(Multi-selection works here.)
The item(s) appear in the Selected Items box on the right.
4. Repeat the process above to add all the items that you want to include then click OK.
5. Click Select under Work Item Properties Sidebar Fields for Cards and add items like you did in
Steps 3 and 4 then click OK.
With Control Charts, you can compare the time spent on Work Items in a variety of ways to glean valuable
productivity metrics. (By defining different workflow states in the From states and To state fields.)
The metric calculated does not only have to be how much time a Work Item spent in a particular status (or
statuses), but there are other metrics as well.
Note
Control Charts determine Work Days based on the Working Calendar.
Medians or averages (total time or moving) are calculated and shown together with their confidence
interval.
Caution
State Names might change when Control Charts are updated from a previous version because their
Scope increases from the Project level to the Repository level. (Their IDs remain the same.)
They can also help you determine whether data from a current Agile sprint can be used to estimate future
performance. The less the Cycle time of an issue varies, the more confident you can be using the mean (or
median) to gauge future performance.
The dots represent a Work Item or a cluster of Work Items. Their vertical position represents the tracked
time interval. Their horizontal position represents when the Work Items were moved into their final status.
For each batch of selected Work Items, the aggregate (median or average) and its confidence interval
(a range that you're confident contains the true value you're looking for), are calculated for both the
total time and the moving window. (A moving window is a way to isolate subsets of a long string of
time-dependent measurements.)
Note
The estimated lower bound of a Confidence Interval may drop below zero for a data sample that is too
scattered or too small because a normal distribution (bell curve) is assumed.
Note
Control Chart widgets ignore Baselines and always display HEAD revision data.
Procedure
1. Select a LiveReport, Info Page, or a Plan and launch the Widgets sidebar.
b. Choose a LiveReport or Info page from a Space under the Documents & Pages
topic.
d. Click Edit.
a. For a Plan:
• Process Cycle Efficiency: The Worked On metric divided by the Days Interval metric.
7. Select an Aggregate option.
The type of aggregation done for a metric over a series. (Median or Average)
8. Select a Scope. (A single Project or the entire Repository.)
The selected Scope is applied to the following parameters:
• All queries.
• The From states.
• The To states.
• Child backlink roles.
9. Enter one or more Sets in the Series section.
a. Enter a Name.
b. Enter a Color to represent the set in the Control Chart, Statistics Table and/or Cluster Analysis.
Supports color names - Red, Hex - #ef6262 or RGBA - rgba(239, 98, 98, 1) formats.
c. Enter a Lucene query in the Query field to define the range of Work Items to include.
For example: type:(userstory) AND NOT storyType.KEY:(feature enhancement)
AND backlog.KEY:(teamA teamB teamC teamD) AND resolvedOn:[20190409 TO
30000000]
Tip
You can construct a query graphically.
17. Select the output that you'd like to appear on the Page from the Available Items column, click to
add them to the Selected Items column and click OK.
(Control Chart, Statistics Table and Cluster Analysis examples.)
18. Click Apply.
The selected components are rendered on the page.
Statistics Table
The Statistics Table lists all the essential productivity data points of a Control Chart in an easy to read
table.
Cluster Analysis
A Cluster Analysis groups (clusters) a set of objects based on their similarities compared to objects in the
other clusters.
You can configure Control Charts to track time intervals based on any Work Item workflow state. (You're
not limited to comparing Cycle and Lead times.) That being said, comparing Cycle and Lead time charts
can help identify what's causing delivery delays.
• Lead Time: The total time it takes to process and complete a user story.
The clock starts ticking from the moment the user story is created and only stops when the story and its
Work Items have all been moved to their final state. (Done, Verified or whatever the final workflow state
is set to.)
An example of a Lead Time Control Chart:
◦ Metric type: Time Interval
◦ From states: Set the From state to the initial Work Item workflow state. (For example, Draft.)
◦ To state: Verified
◦ Query: project.id:elibrary AND type:userstory
• Cycle Time: The amount of time a Team actually spends working on a user story.
Tip
The less an issue's cycle time varies, increases the confidence that you can use the mean or median to
gauge future performance.
You can provide a limited level of interactivity in reports using Page Parameters. This is considered an
advanced feature. It enables you to provide report viewers with some options for selecting the data they
want to see. For example, you might enable users to select a date range for a trend chart or the number of
rows they want to see in a table.
Page Parameters can only be used with many of the Widgets, and some of their parameters. You can
tell if a parameter can be associated with a Page Parameter by clicking the small gear displayed in its
section of the Widget's Parameters sidebar, and then clicking Parameters to show the Page Parameters
compatible with that Widget Parameter, if any have been defined.
Note
You can only have one Page Parameter widget on a Page. You need to decide what parameter values
you want report viewers to be able to change in which widgets, define Page Parameters for them, and
specify all of them in the single allowed Page Parameters Widget.
For example, suppose a Page contains a multi line trend chart, one or two pie charts, and two tables.
You might decide to allow report viewers to interactively specify:
At runtime, the Page Parameter includes an action Save as Default. A user can change the values and
click this link to have the changed values become the defaults. Other users accessing the page see the
values in the Page Parameter widget.
Tip
The Report Designer's Page Script sidebar lets you write a Velocity script to set values for the
$pageContext variable.
See the Use a Page script section for available actions and exceptions.
Assuming the Page is otherwise complete, with the Widget parameters all configured, the first step in
providing user interactivity is to add the Page Parameters.
Three Page Parameters are needed for the example stated earlier in this topic. You add new Page
Parameters using the Parameter button, which drops down a menu of data types:
• String
• Integer
• Boolean
• Enumeration
(Currently, only Enumeration Page Parameters support multi-select dialogs.)
• Date
Each Page Parameter must correspond to the data type it will manipulate in the Widget(s). For example,
to allow users to set a Start Date in a trend chart, the Page Parameter must be of the Date type.
To allow users to specify the number of rows to show in a table Widget, the Page Parameter must be of
Integer type.
When creating String, Integer, Boolean or Date Page Parameters you must specify two properties:
Name and ID. Name is what report users see on the page. ID is the identifier used by the system. By
default, the values are identical. The difference is that ID supports only ASCII characters. If you need the
label to display a different character set, specify ID using only ASCII characters, and Label using your
language's character set.
• Scope: Default is the current project. You can optionally select Repository, or another project. The
selection here determines the types available in the Work Item Types list and the enumerations
available in the Enumeration field's pick-list.
• Work Item Types: The types configured in the selected Scope appear in the list. The selection here
affects the list of enumerations in the Enumeration field. Depending on the selection it may refine the
list and filter out some of the items present as a result of the selection in Scope.
• Enumeration: The enumerations (default and custom) for the selected Work Item type in the selected
scope appear in the list.
• Allow Multiple Values: Lets you select multiple values by the page developer, and later by the page
user.
(Multiple value dialogs for Enumeration support multi-select.)
• Allow No Values: Allows you to omit a value for the Page Parameter. The -- not selected – option
appears to users in the drop-down list of enumeration values.
For example, you might want a Page Parameter to enable Page users to specify the specific types of Work
Items planned in some Plan for some release... Requirements without Test Cases, for example.
The parameters needed for the example for this topic are:
After defining the Page Parameters, they must be "connected" to the parameters of the Widgets they
manipulate. For example, the Page Parameter Dating From needs to be connected to the Dates -
From parameter of the multi line trend chart widget:
You can tell if the Widget can be manipulated via an existing Page Parameter by clicking the gear icon
in a Widget parameter, and clicking again on Parameters. This displays the Page Parameters that are
compatible with this Widget parameter. Check the Page Parameter you want to use. In this example, you
can check Dating From to connect that Page Parameter to this Widget parameter. The end result for your
report users is that they can select the start date in the date range rendered by the chart.
Tip
Several chart Widgets have Date type parameters. These can be either absolute or relative dates.
Relative means the retrieved data is relative to some point in time, such as "Today", "2 weeks ago", or "6
months ago" rather than for some concrete data such as "January 22, 2014".
The report author can specify either or both for a Date type Widget parameter. A Page Parameter linked
to such a Widget parameter renders the user's input options accordingly.
• The Advanced Show Top Rows parameter of the Table Block Widget is set to 10 in the Widget
parameters. By clicking the gear icon and Parameters, you can select the Table Rows parameter,
connecting the Widget parameter to that Page Parameter. Report users can then change the number of
rows displayed in the table.
• The Show Data Labels parameter of the pie chart Widgets can be similarly connected to the previously
defined Page Parameter labeled "Show Pie Chart Labels". By connecting both pie chart Widgets this way,
the Page Parameter will manipulate both. Report users can then show or hide the pie chart labels.
The final step is to add a Page Parameters - Block Widget to the Page. Recall that you can only have one
of these Widgets on a Page. This is the element that provides visual controls for report users. Like other
Widgets, this one has its own set of Widget parameters. For this example, they are set as follows:
• Title: This is some short text to provide a hint for report users. For the example, the Title might be "Your
Options For This Report".
• Page Parameters: Select which of the defined Page Parameters you want report users to be able to see
and use. Click the Select button, and in the Select Items dialog, select the Page Parameters the Widget
should display for the list of defined Page Parameters.
• Width: The width (in pixels) of the Widget in the report Page.
After saving the Page, users with permission to read Pages are able to view the Page and change the Page
Parameters in the Widget to alter what they see in the connected Widgets in the Page.
Tip
See Interactive Reports via Page Parameters to learn more about the types of Page Parameters you
can add.
Procedure
4. Enter a Label.
(The ID will be filled in automatically with whatever you enter for the Label.)
5. Select the Allow multiple values option to permit multiple values (configured via a dual list box
dialog) or leave it unselected to limit the selection to a single value (via drop-down menu).
Tip
If you've inserted an Enumeration page parameter, you can select more than one at a time.
• You can move multiple items at the same time using the arrows.
(Or Ctrl and the ↑ or ↓ arrows on the keyboard.)
Gaps between selected items are removed and they're grouped together when you begin moving them
up and down.
Scripted Chart
Procedure
1. Select a LiveReport, Info Page, or a Plan and launch the Widget sidebar.
2. Click in the paragraph that you want to add the Widget to.
You can add a new paragraph box before or after the existing boxes or resize them.
5. Add a Velocity or JavaScript into the Script field. If you don't have a script of your own, you can paste
the example below in and customize it.
{
chart: {
type: 'areaspline'
},
title: {
text: 'Average Weekly Fruit Consumption'
},
xAxis: {
categories: [
'Monday',
'Tuesday',
'Wednesday',
'Thursday',
'Friday',
'Saturday',
'Sunday'
]
},
yAxis: {
title: {
text: 'Kilograms of Fruit'
}
},
series: [{
name: 'John',
data: [3, 4, 3, 5, 4, 10, 12]
}, {
name: 'Jane',
data: [1, 3, 4, 3, 3, 5, 4]
}]
}
Click F11 to adjust the script in full-screen mode and ESC to exit full-screen mode.
6. Click Apply. The charts are rendered and appear on the page.
7. Click Save.
Here are some things you can try before sending your chart to a widget developer for inspection.
Procedure
1. Debug the chart using the web browser's built in developer tools.
a. Click on the chart (so that it's highlighted in yellow), and then right click and select Inspect
(Chrome), Inspect Element (Firefox), or F12 (Edge).
b. Click on the Console tab that appears on the bottom half of the browser.
c. Click on the link beside the error.
The browser jumps right to the line in the chart's code that is causing the error.
Tip
A common Velocity script error is failure to correctly escape single-quote characters.
When scripting in Velocity, if a value contains a single quote (for example, Matt's) it must be escaped
using the $esc.javascript(...) method.
A simple but useful report is one that shows a chart of unresolved Work Items with high severity values
currently in the repository, separated by Work Item type, reporting also the total number of Blocker and
Critical defects. Such a report requires only two Widgets:
After placing the pie chart Widget in some region of the Page, set its parameters as follows:
• Title: Enter a title that describes what the chart shows, for example, something like "Unresolved Blocker
& Critical Work Items by Type".
• Scope: Specify the scope, in this case, the chart is reporting across the entire repository, so Repository
is selected in this parameter.
• Query Type: Specify the query type. This example uses Lucene because it provides the possibility to
build queries visually. (Report authors who know Velocity or SQL can opt for to use these types of
queries.)
• Type: Specify the artifact type. For this report, Work Items is used, so Work Item is selected for this
parameter.
• Query: Specify the query; for this chart, two query elements are needed. The report is for unresolved
Work Items, so the first query element is for that. Simply choose Unresolved in the Favorites section of
the Query Builder. Then add another query element to select the severity level of the unresolved items.
Select Severity in the Query Builder panel. The report is to show items with Blocker or Critical severity,
so select both of these in the value picker before closing it.
• Separate By: Select Type in this field to separate the matched items by type. Recall that the report is
supposed to show Blocker and Critical items by Work Item Type. The chart Widget makes this quite easy.
• Show Data Labels: Specify whether or not the pie chart's wedges are labeled. The Yes option is a good
choice in this example.
• Show Zero Values: Specify whether or not the chart should include a segment for zero matched items.
For example, are no Change Requests with Blocker or Critical severity, selecting Yes causes the chart to
render a small wedge reflecting this.
Remember to click Apply to reflect changes in the chart rendering on the Page. To complete this report as
specified, add a paragraph above or below the chart Widget, and add an Object count - Inline Widget at
the insertion point. Set this Widget's parameters as follows:
• Scope: Select Repository, because the requirement is to report a count of items in the repository.
• Query Type: Select Lucene to keep things simple.
• Type: Refine so that only Defect type Work Items are counted. If the repository contains this type, it
appears in the types list under Work Items. This example assumes there is a type Defect and selects that
type in this parameter. Now the Widget renders a count of only Defect type items.
• Query: Because Lucene is the query type, the Visual Query Builder is available. Again, two visual
elements are needed: one to select only unresolved items, and one to select the severity levels to be
included in the count. In this case, Blocker and Critical are selected.
If you click Apply, a number appears in the paragraph of the Page where you inserted the Widget.
However, another user reading the Page will not know what the number means.
• Text Before and Text After: These fields provide a quick way to include some explanatory text before
and after the object count.
In this example, the report author might enter There are currently in the Text Before
parameter, and BLOCKER & CRITICAL Defects in the repository. in the Text After
parameter. When Apply is clicked, the Widget renders There are currently 42 BLOCKER &
CRITICAL Defects in the repository., assuming there are 42 items that match the query in
the parameters.
Charts showing trends can be highly useful. For example, suppose you are interested in comparing the
trend of high-severity vs. low-severity Issue type Work Items. This is easily done with the Multi Line
Trend Chart. You can configure the chart with one data set to show high-severity items and one to show
low-severity items. If you want to see more tends in the chart, you can add more data sets.
Procedure
1. Place a Multi Line Trend Chart Widget in some region of the Page.
2. In the default Set, specify the scope of the Work Items (a project or the entire Repository), select
Lucene as the query type. Then in the Query section of the Set, build a query with two elements:
• Type: Issue
• Severity: Basic, Low (or whatever the lowest severity values are for the Work Item type Issue in
the selected Scope).
Set other fields such as:
• Name: Low Severity
• Color: Gray
3. Now click Add Set and configure the second Set to query for high-severity Issue type items, naming
the Set High Severity, and using a different color, such as Red. For Widgets that have the Color
parameter, you can specify common color names supported in HTML (Red, Blue, Cyan, Black, etc.) or
hexadecimal values (#ed1c24, #0000ff, etc.) For example, multi data set type chart Widgets use the
Color parameter to visually differentiate the data.
4. Enter a date range in the Dates parameter. This parameter is available in chart Widgets where the
data retrieved need to be filtered by a date range. The From and To fields enable you to configure
the time scope of the trends you want the chart to reflect. The Horizontal Scale Axis enables you to
set the frequency of points plotted, and when plot points are calculated. For example if the scale is
Month, you might specify a plot point value of 1, meaning data from the first day of each month is
used for the plot point.
5. Click Apply to reflect the configuration in the chart on the Page.
If you want to configure additional Sets, use Add Set. Configure each one as desired, building a query in
each Set to retrieve the data you want, which will appear as another line in the chart.
Tip
The Multi Data Set Pie Chart also provides the possibility to reflect multiple sets of data in a pie chart
format.
You can use the Widgets in the Plans group to report information about Plans such as activity and
progress, and provide some interactivity such as creating a new child Plan, setting Plan status, and opening
a Plan. The Widgets for this example are:
• Plan Label
• Plan Status Button
• Open Plan in Table
• Plan Activity Stream
• Plan Progress
Plan Label
Create a new region and insert an appropriate heading (Release Plan, for example). Below the heading
insert a Plan Label Widget. This Widget shows the name of a Plan, which is a hyperlink that opens the
Plan. It displays any existing child Plans, with the same hyperlinking to open them. It also provides the
Procedure
1. Use Select to select the Plan you want for which you want to report information. For purposes of this
example, select a Release plan.
2. Assume you want to allow users to create a new child Plan directly from the Page. In the Child
Template field, use the Select button and choose a template to be the basis for child Plans of the one
specified in the Plan field. For purposes of this example, select Iteration, as an iteration Plan would
typically be a child of a release Plan.
3. In Show Add Button, click Yes. This allows users who have permission to create new Plans to do so
from the finished Page.
4. Click Apply to complete the configuration of this Widget.
Beneath the Plan Label widget, insert these Widgets, leaving a few horizontal spaces between them:
In the parameters for both these Widgets, select the same plan you selected in the Plan Label widget.
With these Widgets in place and configured, a Page user is able to open the Work Items of the specified
Plan in the Work Items table, and change the status of the specified Plan directly from the Page.
On your Page, you can easily show the Activity Stream of any Plan, enabling users to see the latest
activities. To do this:
Procedure
1. Create a new region below the one you created earlier, and enter some heading like "Plan Activity".
2. Place a Plan Activity Stream Widget into the region, and use the Select button in the Parameters
sidebar to select a Plan. For the purposes of this example, select the same Plan you selected in the
Plan Label widget parameters.
3. Expand the Advanced field and enter a number in Max. number activities to show. For example, if
you enter 5, the stream in the finished page shows only the five most recent activities on the selected
Plan. The Widget running in the finished Page enables users to see more activities.
4. Click Apply to finish the configuration of this Widget.
Plan Progress
The Plan Progress Widget renders a graph and statistics of a selected Plan that show the current progress
of the Plan. The information is updated when a user loads the finished Page. Refreshing the Page refreshes
the information.
Procedure
1. On the region menu of the region you added above, choose Split Region or create a new region
wherever you want on the Page, and add a heading like "Plan Progress".
2. Insert a Plan Progress widget in the new region beneath the heading.
3. In the Plan use the Select Plan button to select the same Plan you selected earlier in the Plan Label
Widget.
4. Review the two options Show Ideal Progress and Show "To Do". This information is shown by
default. If you want to exclude one or both, click No in the option field.
5. Optionally set the chart width. Expand Advanced and enter a value in pixels or percentage. For
example: 600px or 85%.
6. Click Apply to finish the Widget configuration.
7. Click Save.
8. Click Back. The Page is now ready for users.
A test manager may not want to grant testers full access to Test Runs, where they could access templates,
properties, and other features, but still wants to enable them to view information about a Test Run and
even execute it. Using special Widgets in the Test Runs category of the Widgets sidebar, the manager can
quickly construct a Page that...
Procedure
1. Create a new LiveReport type Page and give it an appropriate name. This name appears formatted as
Title in the new Page. Do not make the page name the same as the Test Run name because a Widget
will display that. Consider if you might want to reuse the Page for different Test Runs over time and if
so, make the page name more or less generic.
2. Under the title text, place a Test Run Label Widget. In the Widget's parameters, click the Select
button, and in the dialog select the Test Run for which you are building the Page. You can optionally
choose whether to have the Widget display the name of the Test Run Template from which the Test
Run is derived, in addition to the Test Run's name. Always click Apply when finished with parameters.
It is generally useful for the page to show the current status of the Test Run and the Test Cases selected for
it.
Procedure
1. Insert a new region below the first one and split it.
2. In the left region, type a heading like "Status Overview" and format it as e.g. Heading 2. Then, under
the heading, insert a Test Run Overview Widget, and in its parameters, select the same Test Run as
you selected in step 2 above, and click Apply.
Note
You will select the same Test Run for all Widgets in this Page, since this example deals with only one Test
Run.
You can set up the Page to enable testers to execute the Test Run (they must have the necessary
permission for this). The example page will enable both internal execution in Polarion and external
execution of the Test Run via Excel round-trip. On a real page, you would most likely provide only one of
these options.
Procedure
1. In the new empty region on the right, type a heading Execute Test Run and format it as before.
Under the heading, insert an Execute Test Run Button Widget, select the Test Run in its parameters.
You can optionally specify sorting of the Test Cases. Click Apply when finished.
Tip
Center-align the Widget in the region.
2. Under the button Widget, insert two additional Widgets: Export Tests and Import Manual Test
Results. In the parameters of each one, select the Test Run.
In the export Widget, you can optionally select a subset of the Test Run's Test Cases by means of a
query. For example, it make sense to only export Test Cases with the Open status (status:open).
This and the remaining parameters are optional:
• Specify the name of the Excel export template that should be used by the exporter only if you have
some custom export templates and do not want the default template to be used.
• Specify a file name. A default file name for the exported Excel file is used if you don't.
• (Optional) Change the label displayed to users. For example, if you have a query to select only
open Test Cases, you can change the label to, e.g. Export Open Test Cases to Excel.
3. Under the export Widget, place an Import Manual Test Results Widget. Select the Test Run as with the
other Widgets, and optionally change the Widget label. Click Apply when finished.
4. Add a new region to the bottom of the Page and split it in preparation for the next steps. This is a
good time to save your work in progress.
In the new left-hand region, create a heading like "Set Test Run Status", and under it insert a Test Run
Status Button Widget and select the Test Run in its parameters.
You should only implement this if your project is configured to use electronic signatures for Test Runs.
Procedure
1. In the empty right-hand region, create a heading like "Electronic Signatures", and under it insert a
Test Run Signatures Widget and select the Test Run in its parameters.
2. Click Apply when finished.
3. Add a new region to the bottom of the Page in preparation for the next steps. (Do not split it.)
Procedure
1. In the new region, insert a Test Records Widget and select the Test Run in its parameters. In the
Columns parameter, select which test record information you want to display in the Page.
2. Click Apply when finished.
There are some other Test Run related Widgets not used in this example:
• Test Run Activity renders the selected Test Run's activity stream in the page.
• Import Automated Test Results enables the Page user to select a file with xUnit test results and import
it to the specified Test Run.
The visual report building capabilities of Pages are designed to meet the needs of a broad spectrum of
users, and to make it easy for non programmers to build useful reports. Advanced users and developers
may wish to implement custom scripting or programming in Pages. Two Widgets are provided for such
users:
When one of these Widgets is placed into a Page, the Parameters sidebar opens and displays a simple
source code editor where the developer can write or paste source code. Velocity is the recommended
scripting language. Macros and variables are supported.
Warning
Poorly written code on a Wiki or LiveDoc ™ (Rich Text) page can leave your system open to XSS
(Cross-site scripting) attacks using malicious Work Item and API calls. (Anything, Java code included, can
be added to a Work Item in the document and the API will return the actual value of the target fields.)
A good starting point for custom-scripted widgets may be to reuse an existing widget that is already
configured, and modify it with some additional code. You can copy the source code of any existing Widget
and past it into a Script Widget, after which you can begin modifying the code.
2. On the header of the Widget, click the Actions icon and select Copy Widget Source Code.
3. Add a Script widget to the page and past the source code from your clipboard into the source editor in
the Parameters sidebar.
You are now ready to modify the Widget source code as desired.
Note
Work Item Properties sidebar or drag and drop features:
To use the Work Item Properties sidebar or drag and drop features, a unique widget ID must be
specified for each item within a selected Script Block.
See Making Widget's Work for details about these widget features.
Advanced report developers can use the Page Script sidebar of the Report Designer to write a Velocity
script which can set values to the $pageContext variable. The page script can use the same context
variables as script widgets with following exceptions:
This $pageContext variable is then available for all Widgets on the Page, but its value cannot be modified
by the Widgets or the UI. Typical usage scenarios include:
• Prepare data in a Velocity variable and use that variable in Velocity content of different Widgets on the
Page (such as Script block or any Widget with a data set) so that they use the same input.
• Prepare data in a Page parameter and bind that parameter to different Widgets on the Page, so that they
use the same input.
• Define Page parameters via this script which cannot be edited via the user interface.
• Show Result displays the result of executing the page script, which can be useful for script debugging.
• Show Log displays errors and warning logged by Velocity during page script execution.
• Full screen at the bottom of the sidebar displays the script editor in full-screen mode. Press Esc to return
to sidebar mode.
Note
The script does not affect any Widgets in the Page until you click the Apply button.
Because rendering of the Widgets may be running concurrently, the objects placed in the
$pageContextvariable must be thread-safe if accessed by more than one Widget in the Page.
For more detailed usage information and examples, please refer to the Widgets SDK documentation,
included with the Polarion SDK.
Widgets can be tagged by categories, and users can easily find Widgets by category. There is set of
predefined categories for Polarion Widgets, but widget developers can also set their own categories for
Velocity widgets.
Tags for Velocity Widgets are defined in widget.properties via property tags, which can have
a comma-separated list of values, for example, tags=Work Items, Planning. Categories are
alphabetically sorted, with the exception of All, which is always first, and Untagged, which is always
last.
When you select SQL or SQL + Velocity as the Query Type, an editor displays in the sidebar, and a default
SQL query is loaded. Query syntax rendered in gray is not editable. The parts of the statement that you can
edit are highlighted in light blue when you click on them. They are just comment lines containing a hint as
to what is expected in that specific part of the SQL query.
SQL is generally used only for complex join-type queries that, if done with Lucene, tend to impact overall
system performance.
Note
Invalid SQL commands and symbols: (Implemented for security purposes)
• Some SQL commands and symbols are not allowed in SQL queries.
System Administrators define what's invalid in the polarion.properties file with the following
property:
◦ com.polarion.platform.sql.invalidCommands
• Exceptions from PostgreSQL are not propagated to client-side error messages. Instead, they are added
to the logs as ERRORs.
• See the default list for this property by searching for it in the System Configuration Properties
Reference document.
• If you find that SQL type queries that were working result in errors after you have updated to a new
Polarion version, it may be due to Polarion's transition to a new integrated database, especially if the
version you updated was more than a few releases old. Please consult Polarion technical support on
Support Center.
You may want to provide an easy and visually prominent way for Page users to execute some action that
is not provided by any Widget. You can use the Generic Button Widget, found on the Generic tab of the
Widgets sidebar. This Widget can be configured to execute an action or open a URL. The latter is a simple
matter of entering a valid URL in the Widget's URL parameter. Invoking execution of any other action
requires programming in the Click Handler parameter.
• If the Label parameter is empty, the button label defaults to the word Execute.
• Developers can enter Velocity script and use the Polarion Rendering API in Sub-label, Click
Handler and Disable Logic parameters.
• The Sub-label parameter is optional and requires script programming. HTML and CSS mark-up are
not allowed.
• The Click Handler parameter is required if the URL parameter is empty.
You can create builder JsActionsBuilder and call methods to create several objects. Basic syntax:
$renderingContext.createJsActionsBuilder(). For more details including actions and
parameters see SDK documentation at
sdk/doc/javadoc-rendering/com/polarion/alm/shared/api/utils/js/
JsActionsBuilder.html.
• The Disable Logic parameter is a script field like Click Handler, in which a developer can write
code to conditionally disable the button. For example, you might want to disable it in historical views.
The script returns reason why the button is disabled, which appears in the button tooltip. If the returned
value is an empty string, the button is enabled.
• The Label Color accepts any CSS color, which is rendered in the button label.
• If the URL parameter is used, the button is clickable in exported PDF. Otherwise, it is disabled in
exported PDF.
For some Pages or reports, showing a stream of different activities on the page can be useful. The Activity
Stream Widget (Generic tab of the Widgets sidebar) makes this very easy to do. You can opt to show
one or more types of portal activities on the page by selecting from a list of sources in the Activity
Sources parameter. Activity sources include things like Work Items, Builds, Test Runs, etc.
You can show activities from the current project (the default), another project, or entire repository via the
Scope parameter.
The Query parameter enables you to enter query to retrieve the activities to display. Activity
Source-specific fields are indexed with prefixes. These are the fields to be used in the
Query parameter: workitem.type, workitem.id, workitem.revision, job.rootJob,
job.name, job.worker, job.info, revision.name, build.tag, build.stamp,
build.artifact.groupId, build.artifact.id, build.project.id, testrun.revision,
testrun.groupId, testrun.type, testrun.status.
Both user.name and user.id are indexed for each activity. This can be used to limit the activity stream
to the activity of a specific user. For example, the Query parameter with value eTestman will return only
activities generated by user "eTestman".
To filter activities according to whether or not the indexed field is empty, use HAS_VALUE or
NOT_HAS_VALUE.
You can easily display the contents of any space in any project or in the Repository scope in your Pages.
For example, your project might have a space containing some specification Documents, and you want to
provide your Page users quick access to them from your Page.
The Space Index Widget renders a table listing the Documents, Pages, and Classic Wiki pages currently
existing in a space that you select in the Widget parameters. The name of each listed item is a link that
opens the item. Keep in mind that users must have permission to read the items. Any items for which a
user does not have read permission are skipped and not shown to that user.
The Space Index Widget accesses the same content that is shown on the space's Index page, but renders
it somewhat differently. By default, the Widget limits the display to 20 items (configurable), and the items
are sorted only according to the date they were last updated, with the most recent listed first.
• Select the desired scope in the Scope parameter (required). Items for the current project and the
Repository are present in the list. To select a different project, click Select and choose the desired project
in the dialog.
• Specify the name of space in the Space Name (ID) parameter (required). This is usually the name
that appears in Navigation.
• In the Show Top Pages parameter (under Advanced) you can optionally change the number of items
to show. The default number is 20. Items are sorted by the date they were last updated. To show all
items in the space, leave this parameter empty.
The Diagram Editor adds diagrams to Documents, Work Items within them, and Work Item rich text
fields.
Tip
• Use a Chromium-based browser when using the Diagram Editor.
(There are known issues when working with Firefox and Safari.)
• See the current Known issues and limitations for diagrams before you get started.
• Delete a diagram.
• Print a diagram.
Tip
Keep the following in mind when working with diagrams.
• See www.diagrams.net/doc/ for more information. (Not all of the features described there are
enabled or fully operational in Polarion.)
• While editing a diagram, it's locked and other users cannot edit it until:
◦ Your changes are saved.
◦ You close the Diagram Editor.
◦ The lock timeout is exceeded. (Set via the com.polarion.ui.lock.timeout property by an
administrator. See Advanced System Tuning for details.)
• If Duplicate a Work Item is used on a Work Item while a diagram within it is being edited, any
changes already made to the diagram are saved and included in the new Work Item's copy, but any
changes made after the Duplicate action do not appear in the duplicated diagram.
• Changes to Work Item diagrams are tracked in the Work Item's History but only when the Work Item
itself is saved.
• The language of the Diagram Editor can be set using in the top right corner of the Diagram Editor
dialog. By default, the language is set to Automatic, in which case the Diagram Editor uses the same
language as Polarion.
• The background of a diagram is automatically set to solid white, but you can change the background
to transparent.
• You can import .vsdx files from MS Visio in the Diagram Editor. However, importing older .vsd files
is not always supported.
• If you resize a diagram or SVG image in Polarion and change the aspect ratio, it is malformed when
exported to PDF.
(Unless you also manually resize its attached PNG counterpart.)
The diagrams you create in Documents and Work Items can contain mathematical formulas and links to
other Polarion elements.
Note
See the current Known issues and limitations for diagrams before you get started.
Procedure
1. Open your project and select the Document you want to add a diagram to.
Tip
You can use the search box in Navigation to find it.
Tip
You can add Mathematical Formulas and link diagram elements to Polarion objects or
hyperlinks.
Three versions of the diagram file are attached to your Document's Attachments sidebar.
• diagram_[number].mxg
The file used by the Diagram Editor (draw.io) to store information for further editing.
• diagram_[number].mxg.png
A Portable Network Graphic (PNG) version that is only used when you export a Document to PDF
or Microsoft Word.
(The files are stored within a Work Item's Attachments section when a diagram is added to
their Description.)
• diagram_[number].mxg.svg
The Scalable Vector Graphics (SVG) version that appears in your Document or Work Item.
Links to Polarion elements appear when you hover over the diagram object.
The diagrams you create in Work Items and Documents can contain mathematical formulas and links to
other Polarion elements.
Note
See the current Known issues and limitations for diagrams before you get started.
Procedure
If Table view is not the current view, select it on the top right.
2. Browse or query for your target Work Item, and select it in the table.
3. Scroll down to the Description or another custom Rich Text field and click on its title.
Tip
Rich Text fields contain a toolbar like the Description field.
Tip
You can add mathematical formulas or link diagram elements to Polarion objects or
hyperlinks.
• diagram_[number].mxg
The file used by the Diagram Editor (draw.io) to store information for further editing.
• diagram_[number].mxg.png
A Portable Network Graphic (PNG) version that is only used when you export a Document to PDF
or Microsoft Word.
(The files are stored within a Work Item's Attachments section when a diagram is added to
their Description.)
• diagram_[number].mxg.svg
The Scalable Vector Graphics (SVG) version that appears in your Document or Work Item.
Links to Polarion elements appear when you hover over the diagram object.
Procedure
Tip
See the mathematical typesetting section on Diagrams.net for more information.
Three versions of the diagram file are attached to the Attachments Sidebar in Documents or the
Attachments section in Work Items.
You can add links to diagram elements in the Diagram Editor that also work in Polarion
Procedure
• Link. Then paste your link into the Edit Link dialog box.
• Make a shape clickable: Select a shape Arrange Edit Link. The entire shape is clickable.
The link appears in Polarion when you mouse-over the shape, but you can add blue, underlined
text to make it more prominent
• Copy a Smart Link from Polarion and paste it onto the canvas.
Note
◦ This is not a live link and does not update if the source title is changed.
◦ To update the title on the diagram element, you must delete the text in the diagram element
and repeat the following copy-and-paste procedure.
d. Select the diagram element you want to link the Polarion object with.
e. Paste (Ctrl+V) the link into the diagram editor.
• You can even use drag and drop to associate a diagram element with a Polarion Work Item.
a. Open the Polarion Work Item to associate with the diagram in another browser window.
b. Right click on the target diagram element and click Edit Link.
c. Drag the Work Item's title into the Edit Link dialog.
◦ If copying and pasting a link does not work, use Arrange Edit Link on a shape.
◦ You can select existing text in the diagram and copy/paste.
◦ Diagram links are inactive in preview mode and when exported to PDF or docx.
Three versions of the diagram file are attached to the Attachments Sidebar in Documents or the
Attachments section in Work Items.
Edit a diagram
When you edit a Document or a Work Item field containing a diagram, you can resize diagrams directly,
but you need to open the Diagram Editor to edit them.
Procedure
Procedure
Resize a Diagram
Procedure
Note
• Click to disable Keep Aspect Ratio.
• If you resize a diagram or SVG image in Polarion and change the aspect ratio, it is malformed
when exported to PDF.
(Unless you also manually resize its attached PNG counterpart.)
The Diagram Editor provides an extensive library of shapes, symbols, and clip art images that you can
place into diagrams. These are grouped into categories, and each category appears as an expandable
section in the symbol library panel on the left side of the Diagram Editor. Expand or contract any section
by clicking on the name.
You can control which categories appear in the symbol library panel. Click More Shapes to display a menu
listing all the categories. Categories showing check marks are visible in the panel, while all others are
hidden. Select or deselect any category to show or hide it in the symbol library panel.
When you finish editing a diagram, the visible symbol categories are saved and will appear in the symbol
library panel next time the diagram is edited.
Depending on the type of shape or symbol, you may need to use different actions to insert it into the
diagram. Try clicking on a shape, symbol, or clip art image. A click inserts many elements, especially
block-like elements. If clicking does not insert the element, drag it from the library panel to the diagram
background. Connector type elements in particular may require this action to insert them.
Note
For more information on using mathematical formulas, see Use mathematical typesetting in diagrams
Procedure
Copy a diagram
If you want to copy an existing diagram to another Document, a Work Item, or another place in the same
Document to edit later, copy the diagram's source code to your clipboard and paste it into a new diagram.
Warning
• If you copy and paste the image of the diagram (not the source code) using Ctrl+C and Ctrl+V it
creates a referenced copy of the original.
(Any changes you make to it will also be done in the original.)
• If you just copy and paste the image of the diagram via Copy and Paste in the right mouse click
context menu, it only appears as a preview image and cannot be edited.
Follow the instructions below on how to copy the diagram's source code instead.
A diagram in the Description of a Work Item that's copied to another place in the same Document or
a different Document can still be edited.
Procedure
1. Highlight the diagram you want to copy in a Document or Work Item and click .
3. Select all of the source code, copy it to your clipboard, and click Cancel.
Procedure
Delete a diagram
Procedure
1. If the diagram is in the Description (or other Rich Text field) of a Work Item, click the icon on the top
left to enable editing.
Print a diagram
The File menu of the Diagram Editor includes the Page Setup command and the Print command.
Use these to print a diagram to any accessible local or network printer. Only the currently open diagram is
printed, not the Document that contains it.
Defining and managing requirements with Polarion provides significant advantages over legacy
approaches.
• Best of both worlds support. People who are accustomed to a document-centric approach can continue
to work with documents, while those who need data and tools to manage their work can take that
approach. No one has to give up much in order to work effectively and efficiently in their role.
• Integration of requirements into the overall process. Too often, requirements have been isolated in
office documents that are decoupled from the processes of implementation and testing. With Polarion,
requirements are an integral component of the overall development process from start to finish.
• More efficient and timely collaboration. All stakeholders can have access to the same version of
requirements at all times. Changes are reflected in real time — no delays waiting for emailed copies. The
process is integrated and automated so that no steps are missed or skipped due to miscommunication.
Stakeholders can see the current status, and they are notified automatically as changes take place and
requirements move forward in the process.
• Easier and more robust traceability. Rigorous and thorough traceability has been tough to do with
legacy document-based approaches. Even dedicated point solutions tended to make traceability an
afterthought, and not very visible. Polarion makes deep and broad traceability easy to implement, and
totally transparent.
Note
All Polarion licenses support basic requirements management. You can have a Work Item type named
Requirement which can be linked to other Work Items representing things such as tasks. However,
advanced requirements management features are available only with ALM and Requirements licenses.
Approaches to requirements
Traditionally there have been two main approaches to requirements management that have been more or
less mutually exclusive:
• Document-centric approach — Requirements are defined in office applications like Microsoft Office
Word or Excel, and engineering and QA work from copies of the requirements, which they hope are the
right and most up to date copies.
• Tool-centric approach — Requirements are defined using data-driven software tools such as DOORS,
Requisite Pro, and others. Engineering and QA can manage their processes more efficiently, but the
business and domain experts who author requirements often resist the adoption. Extensive training
becomes necessary for these users when the tools approach is mandated.
Polarion supports both approaches, and even enables a hybrid approach where some requirements and
other artifacts are document-based while others are tool-based. Document-centric workers can stay within
the familiar document paradigm using LiveDocs to author specifications, and marking parts of the content
as requirement artifacts that they and others can track, manage, and trace throughout the life cycle.
Tip
Artifacts that represent requirements, test cases, tasks, and others are collectively called Work Items in
Polarion.
LiveDoc are often referred to as Documents in help text and the Polarion user interface.
People such as developers and QA testers who are accustomed to using data-driven tools can keep within
that paradigm, using integrated tracker, workflow, and project planning and management features to work
efficiently — even when artifacts like requirements live in Documents.
Polarion also makes possible a unique hybrid approach. For example, requirements, test cases, or other
artifacts written up in Documents automatically create data in the background, which is accessible in tools
and reports. Stakeholders can access their preferred presentation — Document or tools. It's quite easy to
switch between these presentations.
Features to explore
• Definitely have a look at Documents. Within that topic, learn about the Word Import feature that
lets you leverage existing assets authored in Microsoft Word, and the Word Round-trip feature that
enables you to collaborate with external people who use Word, or work on your Documents offline and
synchronize your changes with the portal.
Requirements projects
Your requirements exist in the context of a Polarion project. Polarion provides a Project Template
specifically for requirements projects. The template contains preconfigured Work Item types, link roles,
and workflow that are suitable for many requirements projects. We recommend that you create a test
project in a sandbox area of your system, and explore the requirements project template to determine
whether it meets your needs, or if you will need to customize it.
When setting up any project, there are a number of things to consider and plan for. Before starting a new
project for requirements, we recommend the topic Planning for a Project.
Whether written up in Documents, or authored with integrated tools, Requirements in Polarion are a type
of Work Item, that is, an artifact that is tracked and managed through a process. You can customize
your project configuration to support whatever semantics you use. For example, if your organization uses
the Scrum methodology, you might name the Work Item type that represents requirements as User
Story. Regardless of semantics, requirements are tracked and managed the same as any other artifact —
development tasks and change requests, or QA test cases and defect reports. Artifacts created by other
teams can be linked to requirements to create traceability. For example, QA engineers can link Work Items
representing test cases to Work Items of the Requirement type that the test cases verify. Engineering can
link Work Items representing tasks and change requests to the requirement they implement. Work Items
representing defects found by QA can be linked to an implementation Work Item that fixes them, and
easily traced back to that item's requirement or requirements.
When preparing to use Polarion for requirements, you need to think about how the requirement Work
Items you create will be linked to others like tasks and test cases. For example, you will need to decide
what processes will be managed in a given project. Will requirements have a separate project, or will they
be part of the same project used to manage implementation and testing? Maybe Requirements and QA will
have one project, and Engineering a separate project. All approaches are possible. Linking for traceability
across projects is a little more involved than when all artifacts are managed in the same project, but it is
still quite feasible. In any case, your requirements team will need to coordinate with these other teams to
decide the best approach to projects.
Elicitation phase
During the requirements elicitation phase there is typically a need for communication and collaboration,
and for tracking the results of these, to finally come up with defined requirements. The following features
can be used during the elicitation phase while you are still gathering input to process into actual
requirements:
• Documents — Create Documents in the portal, or import Microsoft Word documents. All stakeholders
with access to your project can access Documents and collaborate on the content, with changes
showing up in real time. For information, see Documents and Pages, and the topic on importing
from Microsoft Word.
• Word Round-trip — If you have stakeholders who do not have access to Documents on your Polarion
portal, you can use the Word Round-trip feature to share Documents with them. They can comment
and/or modify content, depending on the permissions granted when exporting. Changes can then be
merged into the source Document in Polarion.
• Pages — You may find Info type Pages useful for collecting and collaboration on information and
content that will eventually become requirements that you copy to LiveDoc Documents, or that you
create in the integrated tracker. For more information, see Working With Pages.
Definition phase
Polarion has several features that you may find useful during the phase when requirements engineers are
actually defining requirements, prior to their review and approval/acceptance.
Approval phase
Polarion makes the process of approving requirements simple and efficient. The following features are the
ones to take a closer look at to support this phase:
• Workflow — Review and approval is just one or two steps in a larger process. That process is defined
in the Project's workflow configuration. Polarion comes with several Project Templates that support
requirements elicitation, authoring, and management. These have preconfigured Document types and
Document workflows suitable for many requirements projects. If the defaults don't reflect your exact
process, Project Templates, and/or individual projects can be customized by administrators to map your
process into the workflows of both Documents and Work Items.
When your process is mapped into the project workflow, then people always know the current status
of a requirement, and what the next step is. For example, when a requirement is created, workflow
might assign it a status of Draft, and define the next possible action as Send to review. When a user
invokes that action, the requirement transitions to a new status — Under review, for example. Then,
the workflow might present possible next actions such as Approve and Reject.
Polarion automatically sends notifications to the relevant stakeholders when transitions occur. The
workflow defines what happens when any action is invoked. For example, the Reject action might set
the status back to Draft. The change can trigger a notification to the author, the assignee, and others.
The Approve action could set a new status like Approved, also resulting in notifications.
The foregoing is a relatively simple scenario. It is also possible to set up Document-specific workflows
that make Document content read-only when the Document has a given status — In Review or
Approved, for example. It is also possible to configure the workflow to require an electronic signature
by users transitioning a Document from one status to another, and/or to provide an electronic
signature when approving an entire Document.
• Auto-assignment — Again, Auto-assignment comes in handy. For example, you could configure
Auto-assignment to reassign requirements to someone when the status changes — to Approved, for
example. Possible assignees might include a developer in engineering, and/or a tester in QA. Again,
appropriate notifications are sent when the status changes, so everyone who must do something with
approved requirements automatically knows it's time to move forward.
Tip
Be sure to have a project administrator look at the Notifications configuration to ensure that your
scheme of notifications works the way you need it to work and notifications always go to all the right
people for every system event, such as the status of a requirement changing.
Common operations
Locate requirements
Requirements are defined in the context of a project, so generally the first step in locating requirements
is to open the project that contains the requirements you want to work with. For information, see Access
projects.
In projects, requirements may be defined in the context of LiveDoc Documents, or they may be defined
directly in the integrated tracker (Navigation Work Items Table), or a combination of the two
approaches may be used. The simplest way to locate the requirements in a project is as follows.
1. In navigation, expand the Work Items topic. The Work Item types currently configured for the
current project appear as child nodes.
2. Click Requirement. The Table views becomes current in the Work Items page and the table contains
all the Requirement type Work Items in the project whether they are defined in a Document or directly
in the tracker.
Work Item types are configurable to support the semantics of any process. In the above steps, if you
don't see Requirement it is because your project has been customized with different types. You would
click on whatever type corresponds to requirements in your organization or project. For example, if your
process is some variant of the Scrum methodology, you might see User Story in Step 2 above rather than
Requirement.
If a requirement you have located is defined in a LiveDoc Document, and you want to edit or view it there,
you can easily open the containing Document. When selected in the top section of the page, the Edit in
Document button appears in the Viewer/Editor toolbar in the lower part of the Work Items page. Click this
button to open the associated Document and go directly to the selected requirement in it.
Access requirements
Once you know how to locate requirements in a project, you will most likely want to access some or all of
them. At a minimum, you need the permission to view Work Items for the project containing requirements.
If you are unable to access requirements, or perform some operation with them, contact the project leader
(usually listed on the project's Home page), or the project administrator to review your user permissions.
In a LiveDoc Document that contains requirements, you can use a query to filter the content to show only
the requirements. See Filter Work Items in a Document.
In any context where the user interface provides the possibility to enter and run a query, you can isolate
Work Items corresponding to requirements using the following query:
type:requirement
Where requirement is the ID of the Work Item type corresponding to a requirement in your specific
project.
Tip
Most contexts where you can specify a query provide the Visual Query Builder tool, which enables you
to construct simple and complex queries without having to know the underlying query language and
syntax.
Special containers for requirements called Modules were provided in Polarion versions prior to version
2011. Modules appear in that and subsequent versions if they existed prior to the upgrade. It is
recommended that users convert any existing Modules to the current LiveDoc Document format. Contact
Polarion Technical Support if you need to convert legacy Modules to LiveDoc Documents.
Create requirements
Note
To create new requirements, you must be granted the permissions to view and to create new Work
Items in the project.
Your approach to creating a new requirement depends on the approach to requirements you have
decided to use with Polarion.
If you have opted to define requirements using LiveDocs, see Work Items in Documents. You can
automatically create requirement artifacts in Polarion when you import a Microsoft Word document. See
Importing Word Documents.
You can optionally create requirement artifacts directly in the project's integrated tracker. Remember that
the Work Item type Requirement is a default type for some project templates, and that some other type
corresponding to requirements may be define in your project configuration.
Procedure
3. In the Table view's toolbar, click and choose Requirement (or the custom type that corresponds
to a requirement in your project). A new Work Item is created.
4. In the Work Item Editor (lower half of the Table view), edit the data fields as needed and click
Save.
Tip
• Enter a Title and Description for your Work Item so that it's readable in all Polarion views.
• See How Work Item Titles are created and updated to learn how Polarion auto-creates and
updates Titles if they are not explicitly defined.
• You can change the Title and Description by opening the Work Item in Table or Tree
view.
Modify requirements
How you go about modifying existing requirements depends on how they are stored (in a LiveDoc or in
the integrated tracker), and what exactly you want to modify.
Modifying requirements defined in a LiveDoc is very straightforward; simply open the LiveDoc and edit it
as you would any office document. Requirements created directly in the integrated tracker must be edited
using that tool. Generally, the Table view is best for changing text content or data fields.
Depending on your requirements and what fields you want to modify, you can use the following editing
options:
• To make essential changes in several fields of a specific Work Item, use the Work Item Editor.
• To update several queried Work Items listed in Table and Tree views, use the Inline Editing
feature.
• To set the same value for several fields in several Work Items, use the Bulk Edit feature.
Procedure
2. Select the desired requirement in the Table view of the Work Items topic.
3. Edit the requirement in the Work Item Editor, located at the bottom portion of the Table view.
Some data fields can be edited in place, that is, without invoking Edit mode on the entire Work Item.
To edit the entire requirement, click the Edit button in the Work Item Editor toolbar in the Table
view.
4. Click Save.
Procedure
2. Select the desired requirement in the Table or Tree view of the Work Items table.
3. Click on an item to select it, then click again to edit it inline.
4. Click Save.
Procedure
2. Select the desired requirements in the Table or Road Map view of the Work Items table.
3. Enter your desired changes in the Work Item Editor at the lower part of the pane.
Note
Some fields cannot be edited using Bulk Edit. Moreover, you can only modify those fields using
Bulk Edit that are available in all of the selected Work Items types.
4. Click Save.
Link requirements
Traceability — from requirements to implementation tasks and source code, to tests, to defects and fixes
— is an important issue for many organizations, especially those in industries where rigorous regulatory
mandates must be met, and compliance must be verifiable. Polarion makes this kind of deep and broad
traceability both easy to achieve, and highly visible. For many projects, the process starts with the
requirements.
The key to success is timely linking of requirements to others, and to other artifact types representing such
things as QA test cases and defect reports, and engineering tasks and change requests. As a requirements
engineer, you will probably be most concerned with linking requirements to other requirements, and
possibly to test cases. Other teams may link their artifacts to your requirements as well, depending on your
organization's traceability needs. As with other common operations, you approach to linking depends on
your basic approach to requirements: Document or tool-based. This topic points you to the features you
need to link requirements for both approaches.
Linking in Documents
You can link the Work Items defined in a Document to other items in the same Document, in a different
Document, or stored directly in the Tracker. See Linking a Document's Work Items.
The table view of the Work Items topic, and the same view of a Document, provide an editor for
Work Item data that you can use to link a requirement to any Work Item of any type. The link can be to
Work Items in your project, or in another project. Linking to Work Items in a different repository is also
possible, but that is an advanced issue, and is not needed for most requirements engineering projects.
The Linked Work Items section of the Work Item Editor provides a graphical interface for linking a selected
requirement with another Work Item. A picker dialog box is available with integrated querying, including
graphical query builder, that you can use to locate the target Work Item for the link.
To familiarize yourself with linking this way, see Linking Work Items.
Export requirements
In Polarion, requirements are a type of Work Item. Consequently, you can use any of the Work Item export
features to export requirements to other formats. For information, see these topics:
Exchange requirements
Polarion supports the exchange or interchange of requirements specifications with external customers or
suppliers who use ReqIF and/or RIF technology. You can import ReqIF or RIF files to new or existing Polarion
LiveDoc Documents. Conversely, you can export LiveDocs to new or existing ReqIF or RIF files.
If your job is to review and approve requirements developed and managed in Polarion, you need to know
how to locate the requirements you need to review, and how to mark them as approved or rejected. There
is no universally applicable procedure. What you must do depends on your organization's development
process, and how that process is mapped into Polarion's workflow. Assuming that has been done, then
you should receive email notifications about requirements that need your attention. This will most likely
happen in response to a status change in a requirement type Work Item: from Draft to Awaiting Approval,
for example.
Polarion fully supports a formal review and approval process. Workflow can be customized with the
necessary statuses and transition actions, as well as automated assignment of items to those responsible
for review and approval. Any type of Work Item, including requirements, can have an approval process built
into its type-specific workflow.
For information on how to review and approve/disapprove Work Items, see Approve or Disapprove Work
Items.
Advanced topics
The Matrix view of Work Items enables you to link multiple Work Items of two different types in a single
operation. This approach can be useful when traceability linking needs to be managed centrally rather
than relying on individual users to link Work Items as they process them day to day. It can also be useful
for correcting incorrect or inappropriate links. For a brief introduction to the Matrix view, see Matrix View.
Linking with the Matrix view is a topic for Advanced users. To learn how to use this feature, see Linking
Work Items in the Matrix View.
Most people will only need to link individual requirements as they create or process them. To learn about
this approach, see the topic Link Work Items.
Traceability reporting
You can use the Matrix View of the Work Items to generate traceability data which can be exported
to spreadsheets or printed as hard copy. For example, you can easily create a report that shows which
requirements have links to test cases, or the analogous artifact type configured for your project.
The following procedure illustrates how to create a report according to this example.
Procedure
1. In Navigation, select Work Items, then in the view selector on the Work Items page, select
Matrix.
2. In the Rows list, select Work Items, then use the Visual Query Builder to construct a query that
returns the requirements you want to export. For example, the following query returns all resolved
requirements:
3. In the Columns list, select Work Items, then use the Visual Query Builder to construct a query that
returns the test cases you want to export. For example, the following query returns all resolved test
cases:
4. Click Search. The matrix shows which requirements are linked to test cases, and just as importantly,
which ones are not linked.
5. Click at the top and choose Export if you want to save the report to a Microsoft Office Excel
sheet, or Print to send the result to a printer.
Note
If requirements and test cases are maintained in different projects, the queries would need to be run
in the scope of a project group, provided that the requirements and test case projects are in the same
project group. If they are in different project groups, then the queries need to be run in the repository
scope. In the latter case, you would need to create the necessary queries to retrieve just the items from
the projects you want to report.
If there too many items in the result set, system performance would degrade for all users if Polarion tried
to render than all in the matrix. In such cases, Polarion displays a message informing you that it cannot
display the items, but that you can still export the results.
Tip
You might explore the possibility of using LiveReport Pages to build traceability reports.
The topics here cover information about Polarion features and common tasks that are of interest mostly
for project managers. Of course some features and topics may overlap with information for software
developers or system administrators. In such cases, this may contain only a cross reference to information
elsewhere in the documentation.
When you are planning to manage a project with Polarion, there are quite a number of issues to
think about. The prefabricated project templates for the different license types are a good way to get
many projects up and running quickly. But other projects may require more thought, planning, and
customization. Where do you begin, and what issues should you think about and explore? The topics here
cover exactly that. Not every issue or every customization mentioned may apply to your situation, but you
can only decide that if you are aware of the possibilities. So let's begin with an overview of the Polarion
features and configurations to consider when gearing up for a new Polarion project.
Project planning actually starts when you create a Project in the Administration interface. At that time you
specify the outer parameters of the project: the starting and ending dates. The project ending date is not
a fixed, permanent date. You can change it any time as the project progresses, extending the project, or
moving the end date up.
Working Calendar
Another important system configuration that affects project planning is the Working Calendar. It tracks
how much overall working time is available. The Working Calendar defines both working time, and
nonworking time such as weekends and holidays. A Polarion administrator should configure the calendar
in the global (Repository) scope. The global calendar generally specifies the organization's normal work
policy — the days and hours when people work, as well as days off for weekends and holidays. The global
calendar configuration is the default for all new projects. Users can configure a personal User Calendar
that defines an individual's work schedule. For example, some people may work only part time. At times,
people may work overtime, take vacation time, or take other time off. Between the global calendar and
the aggregate of all user calendars, the system knows how much total working time is available. For
information on configuring the global calendar, see Configure the Working Calendar. For information on
configuring users' individual calendars, see Configure your User Calendar.
If you have team members who regularly split their working time between two or more projects, an
administrator can configure time splitting in their user accounts. This data is available to various reporting
calculations in the system to account for the available time in the relevant projects. For more information,
see Configuring User Time-splitting.
Time Points are essentially named milestones associated with a date. For example, you might have a Time
Point named "Beta 1" that falls on some date prior to the actual end date of the project. If you practice
iterative development, you can set up a Time Points for each one of your iterations. Once Time Points are
configured for the project, Work Items can be assigned a Time Point. It is then easy to query and view items
that are unresolved for any Time Point. To learn how to configure Time Points, see Configure Time Points.
Tip
Defining Time Points is optional. You may decide you don't need them if you manage projects wit the
Plans feature.
With the foregoing configurations in place, you can begin creating Work Items in the project and providing
values in the Work Item fields related to planning. These include Priority, Severity, Initial Estimate,
Remaining Estimate (estimate of time remaining to complete the item), Due Date, Time Point, and
Planning Constraints, Assignee, and Planned In.
With Polarion, you don't build a project plan in the traditional sense. Rather you concentrate on defining
the Work Items that must be completed in the project's time frame, and for the Time Points within that
time frame. You enter planning data for each Work Item either as it is created or later in planning sessions.
Tip
Once you have the project's Work Items defined and planned, you can always run queries to see what
items are open or resolved for any period of time.
Plans
You can add Work Items to Iterations and Releases in Plans. The latest state, and progress indicators, are
always available online in handy charts and dashboards.
Project templates
Looking into project templates should be a project manager's first step in planning for a new project.
There is a good chance that one of the available templates provides everything needed for your project.
A good way to check this is to create sandbox projects on your own Polarion server. Create test projects
using the templates that seem closest to what you need, and then look at them in terms of the issues
discussed in the following topics to see if the template provides what you need. If the template doesn't
provide what you need, determine what you might need to customize to get you there.
The default project templates provide predefined Work Item types that work well for many software
development projects. You see such types as "Requirement", "Defect", "Change Request", and "Test Case".
But keep in mind that Work Item types can represent literally anything you need them to represent.
In your planning, think about what kinds of artifacts you need represented and processed, and consider
creating custom Work Item types for them. Work Item types are defined in the enumeration configuration
file workitem-type-enum.xml ( Administration Work Items Enumerations). For more
information see Configure Enumerations.
Hand in hand with thinking about custom Work Item types, you need to think about what relationships
can exist between items of your custom types. The standard types provided for software development
have relationships like depends on, relates to, implements, verifies, and so forth. These relationships
are defined in link roles and can be customized to define whatever relationships you need between your
types of Work Items. Then in production, links with one or more link roles can be created between Work
Items of your types, thereby creating exactly the kind of traceability you need. Link roles are defined in
another enumeration configuration file: workitem-link-role-enum.xml ( Administration
Work Items Enumerations). For more information see Configure Enumerations.
Let's assume you defined several custom Work Item types and the link roles that cover all the relationships
that can exist between these types. Some of those relationships should actually exist only between certain
types, and never between other types. For example, you have a link role "fixes" for a relationship that can
exist between Work Item types "Repair" and "Breakdown", but should never exist between Work Item types
"Breakdown" and "Sales Call". That's where Link Role Rules come into play. For each link role you define,
you can also define one or more rules that control between which Work Item types users can create links
with that link role. You can configure the rules on the same page where you define the link roles.
Workflow
Regardless of whether or not you need custom Work Item types and link roles (but especially if you do),
review the workflow customization capabilities for Work Items, Documents and Test Runs. The project
templates provided with Polarion provide workflow configurations that are suitable for many projects
and processes. If the predefined workflows in the project templates do not meet your needs, a Polarion
administrator can configure the workflows for your project to support your process.
Workflow enables you to embed process knowledge in the project to ensure that everyone on the team
complies with the process, even though they may not know all its details. Workflow makes process
compliance seamless and painless. You can set up workflows to ensure that no steps are missed, that
the steps progress in the correct order, and that the right things happen after steps in the process are
completed. A good example is the workflow for a requirements project. Work Items of a Requirement type
can be configured go through a process or review and approval before they go into the implementation
phases. After that phase, they can automatically push to the testing phase. Workflow can be circular. For
example, if a Requirement is not approved, it can reverts to an in-progress state. Or, if a test discovers a
defect, it can revert to an unresolved state.
Electronic Signatures
Tip
You can query a project for all the Documents you have signed or Documents that await your
signature.
Requiring signatures for specific actions or process steps can be configured in the global workflow
configurations for Work Items, Documents, and Test Runs, (as default for all new projects) and
individually in these workflows in individual projects, overriding the global configurations with project-
specific statuses and transitions.
Caution
Your browser might offer to or autofill credentials in forms like e-signatures that use password fields.
Edit your browser settings or enforce the related security policies on managed computers to disable this.
Polarion provides a default set of data fields for Work Items, which are adequate for many teams and
projects. But if you need to track additional data with Work Items, you are not limited to the default fields.
You can define custom fields of various data types. You can make them applicable to all Work Item types,
or limit them to one or more specific types, and you can optionally define them as required fields. For
example, if you have several products and Work Items are somehow applicable to a specific product, you
might create a custom field "Product". You could also create an enumeration to store a list of products
from which users can pick a value when filling in the custom field. Custom fields can be used as search
parameters in queries. For example, if you have a custom "Product" field, users can query for Work Items
that contain a value in that field.
When planning for a new project, give some thought to what additional data you need to track for
each Work Item type, and plan to create custom fields to track it. An administrator can implement your
custom fields in Administration Work Items Custom Fields. For more information, see the
Administrator's Guide topic Configure Custom Fields.
Automatic assignments
You can configure your project to automatically assign newly created Work Items to team members based
on conditions which you specify. This can save a great deal of time over the life of a project and more
than pay back the time spent to set up the auto-assignment rules. Conditions can range from simple (for
example, assign all new items to the project leader), to highly complex where assignment depends on
multiple conditions and values set in several Work Item fields. For example, a complex condition might
be an item assigned to some Category with a certain severity level, and it is assigned a specific Time
Point. When the condition is satisfied, then the new Work Item is automatically assigned to one or more
assignees specified in the auto-assignment rule. Auto-assignment rules might be created so that a new
Work Item with Category value "User Interface" with a severity level "Major" or "Critical" is automatically
assigned to user A, while an item with the same Category value but with severity level "Normal" or "Trivial"
is automatically assigned to user B.
Categories
The standard Work Item field Category enables you to classify Work Items in one or more ways.
Categorizing your project's Work Items provides an additional way to query them. This is useful for
reporting certain subsets of a project's Work Items on LiveReport Pages, or for saved queries that retrieve
frequently-needed sets of Work Items. For example, you might have a category "Usability" for Work Items
that somehow relate to that issue. You can then easily construct a query to retrieve all items assigned the
Usability category, and that were resolved for some time point. You can easily embed that query in a report
widget on a Page. Categories can also be one criterion for automatically assigning newly created Work
Items.
An administrator can define Categories for your project in Administration Work Items
Categories. For more information, see Configure Categories.
To make sure your project launches without issues, you should make sure that everyone on your project
team has a user account and that they have the permissions they need to work on the project. The same
goes for other stakeholders. You may want to look at the global user roles on your Polarion system and
decide if these are right for your project, or whether you need to define project-local roles. For such roles,
you need to consider what permissions are needed for users in each role. For example, suppose you have
a project-local role project_customer for some external user(s) at your customer's company. You may
want that role restricted from accessing some kinds of data, for example, Work Item comments or time
estimates, and also restricted from changing data.
Project Plan
Polarion's approach to project planning is probably different from that of other project planning tools you
may have used. With Polarion, you create Work Items for everything that must be done to complete the
project. These are assigned to team members, either manually, or via the Auto-assignment feature, which
can be customized by administrators. You can work with your administrator to configure workflows that
ensure your process is followed. You then have a choice of how to approach planning the work on a
project.
Time-box approach
This approach centers around Time Points. You work with your administrator to define Time Points in
your project configuration that correspond to milestones you want to meet, and then assign Work Items
to each Time Point. For each Work Item, you and/or your team members estimate the amount of time
needed to resolve it. You can use the Road Map view of Work Items to see how your plans are shaping
up, and review progress. You can also create custom LiveReport Pages that show the project status and
progress in whatever ways are useful to you.
Tip
Use Inline Editing to easily set the configured Time Points for Work Items.
If you have stakeholders who use Microsoft Project, or you have a project defined with that tool that you
want to import into Polarion, see Import from Microsoft Project and Export to Microsoft Project.
Iterative approach
The Plans feature is a newer, iterative approach, recommended for all but very small projects.
Once Work Items are created and assigned, you and your team can create Plans, plan Work Items to
Releases, and to Iterations within them. You then prioritize the Work Items you have planned for each
Iteration and Release. You can then create Plan reports that you and your team can use to monitor and
review progress and status.
This feature tracks the total working time available to projects. The data is important for both
planning approaches. An administrator can configure the global Working Calendar in Administration
( Repository Administration Work Items Working Calendar). Your project team
members can configure their personal Working Calendar in their user account page.
Notifications
The last consideration when getting ready to launch a new project is Notifications. These are configured
globally, and the scheme is inherited by new projects. In most cases, your system's global default scheme
for notifications is OK to begin your project. If you find that you need project-specific tweaks, you can work
with an administrator to modify the project configuration after the project is under way. For example, if
you find that some notifications set in the global notification configuration are not necessary in the context
of your project, your administrator can adjust the notification scheme for the project. If some notifications
are of vital importance, then you should first review the global notification scheme. Global administrator
permissions required for access, so you may need to work with an administrator.
Procedure
If your team uses, or wants to move to the Agile methodology, Polarion can provide significant benefits
in terms of process support and embedded knowledge. Some Polarion Project Templates come with
preconfigured support for Agile software development. You can you can use such templates as the basis
for your own projects. Simply create a new project, and select the template during the process.
Tip
See Agile Software Project for information on what's provided with the template, the default Work
Items, and the Link Roles it's configured with out of the box.
Project Administration
Project managers may be granted administrator permissions for specific projects by the lead Polarion
administrator. This gives a project manager the ability to manage users and roles as well as customize the
system configuration specifically for the project. If you are granted project administrator permissions, you
should review the relevant topics in the Administrator's Guide.
The Work Records feature enables team members to create records of blocks of time spent on specific
assigned items. If your Polarion license provides Work Records, and your process uses this feature, you may
wish to freeze reporting periodically. For example, you may freeze reporting weekly, monthly, or quarterly
in order to understand the costs for some period of time. You do this by configuring a locking date for Work
Record in the project's Administration interface. Work records dated on or before the configured locking
date cannot be modified or removed. For information, see Configure Work Records.
If you're a project lead, project manager, or IT executive, Polarion's live Dashboards provide an information
summary that enables you to view the progress of any project. Dashboards present near or actual,
real-time aggregate information based on the actual progress of planned requirements, tasks, change
requests, defect fixes, and so forth. Of course reviewing dashboards is no substitute for close contact with
your team, but Project dashboards and the features that compile the information displayed can reduce
the amount of time you and your team spend in meetings reporting on progress, so you can focus on
problems and solutions instead. Dashboards can also eliminate the need for developers to write and
managers to review and compile information from periodic status reports.
Polarion also provides managers with the ability to generate a variety of reports with output to both online
and offline formats.
Procedure
1. In Navigation, click on the current project or repository name (under the Polarion logo image), and
choose Open Project. In the dialog box, in the All Projects tab, select the project whose dashboard
you want to see. (If you would like to see dashboard information for a group of projects, select a
project group instead).
2. In the Navigation pane, choose the Dashboard topic.
• Dashboard
• Working with the Dashboard
Generate Reports
The Reports topic provides access to a number of on-screen reports and also to Javadoc documentation for
source code.
You can generate and export a report on developer progress and time spent. In order to get useful data,
your process should have developers estimating Work Item time. See Estimate Work Item Time and
Report Time on Individual Work Items.
The process involves creating a query that isolates the Work Items you want to know about, and then
exporting data to an Excel sheet using a specially-designed report template. The next section details the
procedures.
Build a query:
Which Work Items to include in the time and progress report is up to you. You should become familiar with
querying for Work Items and using the Query Builder to get the subset of Work Items you want for the
report. Run the query from the Table view.
An example of some query parameters might include unresolved items in Project having a Status of
in-progress. You can optionally include some specific assignees.
Tip
Don't forget that you can save any query as a Shortcut for quick reuse later on. See Using Queries and
Shortcuts.
Once you have a query that isolates Work Items for the report, you can generate and export the report.
1. Make sure you are viewing Work Items in the Table view.
2. Click the Actions in the toolbar, and choose Export in the drop-down list. The Export Work
Items dialog box appears.
3. In the Format list, choose xlsx: Microsoft Excel.
4. In the Template list, choose Time Report.
5. (Optional) Add columns to the list of Selected Columns to include in the generated report document.
6. (Optional) Show advanced options and change any settings as desired.
7. Click OK to generate and download the report. You are prompted for a storage location.
To review the generated report, open the downloaded report file in Microsoft Excel or other compatible
application.
It is possible to create Project Baselines in Polarion which mark a state of Work Items in a tracker (usually
a requirements tracker) at some point in time. Later, managers and/or other team members can check
the differences between baselines, or a baseline and the current state of Work Items, by generating and
reviewing Baseline Comparison Reports. Baselines and reports are covered in Project Baselines.
When your process involves project members using Polarion's time recording features when completing
Work Items, it is then possible for managers and others to generate Work Reports which summarize
all Work Records for a project or a user during a specified time period. For information about the time
recording fields and Work records, see Reporting Time and Progress.
Note
Work Reports are generated in Microsoft Excel format.
Procedure
10. Click Start to send a job to the Scheduler. You can check the progress of the job in the Monitor
topic. The time required to generate the report depends on the number of Work Items reported on
and the availability of system resources.
When the report is generated, a link appears in the Work Reports section of the dialog box. The link
text is the file name of the report. You can open or download the report file. The Work Reports section
contains a Refresh button which updated the report from the most current Work Item data.
11. If you want to preserve the report settings for future reuse, check Remember this configuration.
• Nonworking time is indicated by gray background. It is displayed only on rows representing users.
• When the scale of the report is Day, cells representing nonworking days of a user have a gray
background
• When scale is Week or Month, cells representing a week or month, all days of which are nonworking,
have gray background.
An administrator can configure Polarion to run work reports as a scheduled job. For more information, see
Configure the Scheduler and Work Report Job Configuration.
CMMI Report
Caution
CMMI Reports are deprecated and scheduled for removal.
Polarion provides a simplified CMMI compliance report based on the CMMI 1.1 Staged Presentation Level
2 (http://www.sei.cmu.edu/cmmi ). At this stage, it is not advisable to use this report as input for CMMI
certifications. The CMMI report is a collection of pointers on how particular practices are implemented. It
can be useful during preparation of a CMMI appraisal, as the report makes it easy to gather the data and
provide references to established practices.
The report should be used as guideline rather than required rules. A CMMI report that says 0% is
implemented means only that Polarion did not recognize artifacts in the way Polarion defines them. So,
for example, a CMMI report might say there is zero Requirements Management because Polarion found
no Work Items of type Requirement in the project against which the CMMI report was run. However, you
might define and manage requirements in a separate project.
The CMMI report is calculated for the current project, so you need to open the project for which you want
to see the CMMI report. Open the desired project in the Open Project or Project Group dialog box. See
Access Projects.
To run the report, expand the Quality topic in the Navigation pane and select CMMI. The report is
generated on demand and displays in the Content Pane.
Access Projects
When you log on to Polarion, the first thing you normally see is the Repository Home page. (At least this is
the case in a default installation. Depending on the way your Polarion administrator set up the system and
your system permissions, it is possible you could see something different.)
As a developer, you need to access one or more Projects. In order to do that, you need a Polarion user
account, but you must also be assigned a role in each Project you have access to. Project roles are assigned
by a Polarion administrator. (See Configure User Roles).
Once you are set up administratively, navigate to the Project you want to work by launching the Open
Project or Project Group from the Navigation Header.
The projects managed with Polarion are listed in the All Projects tab of the Open Project or Project Group
dialog box. Depending on how projects are organized in your system, the project you are seeking may be
a top-level node in the dialog box, or it may be under a project group or even a Project Sub-group. (You
should be familiar with the organization of your system. For more information, see Access Projects.)
When you locate the project in the Open Project or Project Group dialog box, select it and click OK. The
project's Home page begins loading in your browser. You can either wait for it to load so that you can
review its information, or you can immediately begin navigation to the Work Items topic or any other topic
in the Navigation pane.
Note
Some Polarion systems may be configured to run multiple Polarion servers, and you may be assigned to
projects hosted on different servers. On such systems, when you log on you can select which server you
want to log onto:
While working in a project on one server, you can switch to a project hosted on a different server. In the
topics view of Navigation, click the current project name, and then click Open Project or Project Group. In
the dialog box, the available servers are listed under Switch to Servers.
Work Items are issues you and others need to process to complete the project. Work Items are of different
types representing different artifacts. For software development, common types include Requirement,
Defect, Change Request, and Task. The types and their definitions are fully configurable, both globally and
for each project, so you may see different types in projects you work on.
There are three basic ways you can locate Work Items:
• Use Topics.
If you know the ID of the Work Item you want or some text in its description, you may be able to quickly
locate the Work Item using the Site Search in the Polarion header.
You can use the shortcuts topics in the main navigation panel to access some subset of Work Items.
By default, the Global Shortcuts topic contains a shortcut named My Work Items which accesses all
unresolved Work Items assigned to you and displays them in the Table view of the Work Items topic. Other
shortcuts pull up other sets of Work Items. You can create your own shortcuts from queries you build using
the Query Builder in the Table view of the Work Items topic. See Search Work Items.
Once you have accessed a set of Work Items with a Shortcut, you can use the Query Builder in the Table
and other Work Item views to refine the list of Work Items. See Search Work Items.
The Navigation pane contains navigational links that pull up sets of Work Items. The Work Items topic
accesses all Work Items of all types in the project. Beneath this link are several others which may vary
according to configuration/customization of your system. By default, the following links are present:
Note
The Work Item types may differ depending on the project template used to instantiate the project and/or
any project-specific customization that may have been done.
The list of Work Item types is configurable by a Polarion administrator, so you may see other items such as
Defect or Feature Request which correspond to types of Work Item custom configured for your system.
See Configure Work Items. In every case, clicking on one of these items should access all project Work
Items of the respective type.
Once you have accessed a set of Work Items with a Topic, you can use the Query Builder in the Table and
other Work Item views to refine the list of Work Items.
The Working Calendar tracks the amount of actual working time available to projects. The Working
Calendar defines the working days in a work week, and working hours within each working day. It may also
be configured to specify special nonworking days and times such as public holidays.
If your organization uses this feature for project planning, management, and reporting, you should
check your personal User Calendar before you begin processing Work Items. Your User Calendar tells
the system the days and hours you normally work, and enables you to report exceptions to that, such
as vacation, leave, or other planned time off. This information is available in the system for calculations
related to project status and planning reports. The global Working Calendar is configured by a Polarion
administrator, and it defines the standard working time, holidays, and so forth for your company. This
information appears by default in your User Calendar.
You only need to change your User Calendar when your work schedule differs from that defined in the
global Working Calendar. You can specify personal time off such as vacations, or leaves of absence. You can
also log temporary schedule differences. For example, if you plan to take several hours per week off over a
period of 3 months to attend some classes, you can configure your User Calendar to reflect this.
Your User Calendar is available on your user profile page. Access this page by clicking the My Account
link in the tool view of Navigation. Scroll the page until you find User Calendar. Click it to load your User
Calendar. You can use the set of graphical controls to make and save changes to your User Calendar.
The Regular Schedule section lists the working days and times of your normal work schedule. By default,
the values are from the global Working Calendar. If your regular working time differs from the global
schedule on one or more working days, you can change the start and end time for the affected day(s).
1. Select the check box beside the day you wish to change. This enables the override of the global
Working Calendar. The Start Time and End Time boxes are now editable.
2. Change the Start Time and/or End Time value(s) as desired.
3. Click Save in the toolbar above the section.
Tip
You can mark any day in the Regular Schedule section as a nonworking day by clicking the icon after
the End Time field.
Suppose you changed the start and/or end time for several week days in your Regular Schedule because
you were working only part time, and now you have started working full time and want to sync your User
Calendar back to the global schedule. To do this, clear the check box next to the modified work day(s) and
save the change.
Schedule exceptions
In the Schedule Exceptions section, you can define exceptions to the regular schedule. Exceptions can be
permanent, or temporary for a specific period of time. For example, suppose you take time off for a holiday
that occurs on the same date every year. This can be set up as a permanent exception to your normal work
schedule. If such a holiday falls on a different date each year, it can be set up as a temporary exception.
• Time Off: The exception is time that will not be available for work in addition to any nonworking time
configured in the Regular Schedule.
• Time Working: The exception is time that will be available for work in addition to the working time
configured in the Regular Schedule.
Procedure
1. Enter a meaningful title for the exception in the Title field, for example, New Years Day Holiday.
2. Select the exception type by choosing a value in the Type drop-down list, for example, Time Off.
3. Specify the date when the schedule exception is to begin in the Date From field in this format:
yyyy-mm-dd. Alternatively, click the calendar icon next to the field and choose a date in the pop-up
calendar, for example, 2008-01-01.
4. If the exception you are defining is temporary, specify the date when it should end in the Date To
field, in the same format as mentioned in the previous step. For a one-day exception like our New
Years Day example, the value should be the same date as in the Date From field. If the exception is
ongoing, leave the Date To field empty.
5. If the exception you are defining occurs only on one specific weekday in the time period defined,
choose that day in the drop-down list in the Weekday column. Otherwise, leave the default value All
days.
6. If the exception you are defining is of the type "Time Working", set appropriate time values in the
Time From and Time To fields, which are enabled when this type is selected. Time From is the time
when the additional working hours start, and Time To is the time when the additional working hours
finish.
7. If you want to add another Schedule Exception, click in the Actions column and repeat the above
steps on the new row that appears.
8. When you are finished defining your Schedule Exception(s), click Save in the Working Calendar
toolbar. To cancel all changes, click Revert.
Procedure
You can edit Work Items in several places, but use the Work Item Editor (form) for extensive edits to a
single artifact.
Tip
• To quickly edit different fields or values in multiple Work Items, you can edit them inline right in the
Work Item tables.
• To edit the same fields in multiple Work Items at once, use Bulk Edit..
(Especially useful for assigning multiple Work Items to the same person, or setting the same Status,
Priority, or Start/End date for several items.)
• Even if you have permissions that let you modify Work Items, some fields might be set to read-only.
3. Edit the desired fields and click Save. (Or Save and Suspect)
Tip
• Some fields are editable without the need to click Edit. Hover over a field for a moment to see
if it can be edited in place.
• You can quickly jump to different sections of the Work Item using the top toolbar buttons below:
◦ Instantly scrolls to the Comments section where you can add and view any comments
about the Work Item.
◦ Instantly scrolls to the Linked Work Item section where you can view all the Work Item's
links (if any).
◦ Instantly scrolls to the Attachments section where you can view and access any files
attached to the Work Item.
◦ Reduces or increases the number of fields shown on the Work Item Editor.
◦ Lets you view the Work Item's View Work Item History. You can drill down into any
revision of the Work Item.
◦ Change what Work Item in the table appears in the Work Item Editor.
◊ Launch the selected Work Item in the Work Item Editor in a new browser tab.
A Work Item can contain a number of data fields. Click to minimize the level of details on the Work
Item toolbar.
(Which fields are displayed or hidden is defined by an administrator in the Form Filters section of Form
Configuration.)
Polarion remembers your preference and displays all other Work Items with the same detail level.
The Work Item editor contains various fields with drop-down menus or lists from which users can select
a value for the field. In some cases, the list of items can be quite long, slowing the page response while
populating. Long lists can also be difficult to browse.
Tip
• Select the drop-down and start typing what you want to speed up the filtering process.
• List filtering works in all drop-down list/combo boxes in Polarion, including dialog boxes. The default
number of items loaded to lists is configurable by an administrator.
The Resource Traceability feature enables developers to create semantic traceability links between
elements in source code (stored in any configured repository) and Work Items. For example, some specific
function in the source code might implement one or more Requirement type Work Items. You can create
such a link by adding a comment before the function, using a prescribed comment syntax to identify the
target item and the link role. Currently supported languages are Java, C, and XML.
For more information about the feature, see Configure Resource Traceability.
For information about the comment syntax to use in source code, see Link a Resource.
In some development organizations, developers are asked to provide an initial time estimate for Work
Items. In other organizations, this is done by a project leader or manager. Polarion provides the capability
to estimate Work Items and track the time actually spent to resolve them. Over time, the data collected is
highly useful to both developers and managers in estimating time to complete projects and understanding
how accurately they can plan.
Procedure
1. Locate the Work Item, and select it to display its details in the lower pane.
Tip
You can edit some Work Item fields directly in the Table and Tree views with the Inline
Editing feature.
2. Click Edit if you need to edit the fields that cannot be edited inline.
3. Locate the Initial Estimate field, and enter the amount of time you think it will take to complete the
Work Item.
4. Enter the same value in the Remaining Estimate field. You adjust this value as you work on the item.
Polarion has a special syntax for entering and displaying time. Using this syntax, you can estimate Work
Item time in days (d + integer), hours (h + integer), or a combination of days and hours. You can
use 1/2 in front of the day or hour symbol to indicate half.
For some examples, click the ? icon to the right of the Initial Estimate field.
It is possible for a system administrator to override the default factional syntax for hour values, and enable
entry and display as decimal values. If this is done, the help dialog box that appears when you click the ?
icon appearing with time fields will indicate that entry of decimal hours is possible. If so, then instead of
1/2 h, you can enter .50.
Polarion makes it easy and fast for developers to report their progress to management. There are several
Work Item fields related to time tracking and planning accuracy analysis:
• Initial Estimate
• Time Spent
• Remaining Estimate
• Status
Tip
You can use the Inline Editing feature to:
In addition to the above fields, Work Items contain the Work Records section. Work Records are useful
when you have to spend several blocks of time on different days to complete a Work Item. You create one
Work Record for each block of time you spend working on the item. Each Work Record updates the Time
Spent and Remaining Estimate fields.
You or your manager can then generate a Work Report that documents your Work Records.
4. Click OK.
Note
The administrator of your project may optionally set a locking date, on and after which you cannot add
or modify Work Records. If you need to compensate for time over-reported in a Work Record that is
locked, you can create a Work Record for the next reporting period with a negative value for time spent.
Your team needs to define the process for using the time estimating and reporting fields and Work
Records. You can use these to facilitate progress reporting.
Assuming that the relevant fields are set as discussed in Estimate Work Item Time, there are two things
you do as you work on a Work Item:
1. When you begin working on an item, go to the Status and select Start Progress in the drop-down
list.
2. As you progress with the item, create a Work Record for every block of time spent on the Work Item.
You can use the Time Sheet view in the Work Items topic to report the time you spent on Work Items
during a period of time which you specify. You can also use this view to edit time already reported
for individual items with Work Records, provided you want to report more time spent on the item than
previously reported in the Work Record. If you want to decrease the amount of time already reported in
a Work Record, you must edit the specific Work Item in the Work Item Editor, accessible by clicking on a
Work Item displayed in the Time Sheet. The Time Sheet view itself is essentially a convenient and quick
way to create Work Reports on a number of Work Items without having to select each one in turn.
• Search Query: Use to fetch a set of Work Items, specify a period of time for which to report time spent,
and save or cancel changes.
• Filtering: Filter the set of Work Items according to time, and optionally select only items with Work
Records and/or Work Records logged by you.
• Time Sheet grid: Use to report time spent on listed Work Items during the period shown. Rows are Work
Items fetched by a normal query.
Procedure
1. Create a query to display a set of Work Items that contains the ones for which you want to report time
spent, and to show a specific span of time in which you want to report hours spent.
2. Locate the row for a Work Item on which you want to report time spent.
3. Enter the amount of time spent in the column for the appropriate date.
4. Save the edits when finished.
Tip
If you regularly split your working time between two or more projects, you can configure time splitting
in your user account. This helps increase project planning accuracy. For information on this configuration
see Configure User Time-splitting. You can make this configuration yourself in your own user account.
Click My Account in the tool view of Navigation.
You can quickly and easily add any number of textual comments to a Work Item. This can facilitate
discussion of the item between team members in the same or a remote location. For example, a developer
in Delhi may need some additional information from an architect in New York. The developer can add a
comment and reassign the Work Item to the architect, which creates a notification for the architect. The
architect can respond with another comment, and perhaps some attachment, and reassign the item back
to the developer.
1. Click Comments in the Detail pane toolbar to quick-scroll to the Comments section.
2. At the bottom of the Comments section, click the small Edit button. An edit form appears in the
Detail pane.
3. Type your comment and click Save.
When you finish working on a Work Item, it's time to indicate it in Polarion. By so doing, the project plan
and overall status is automatically updated, and your project manager can follow your progress without
the need for you to write a status report.
1. After locating the Work Item via navigation or search, select it in the Table (or other) view to display
its details in the Detail pane.
2. Locate the Status field, and click the drop-down button to display the list of next workflow actions.
3. Select the workflow action that is required by your team's process. Workflow is customizable by a
Polarion administrator, so the list of actions may differ from the default. The default actions are
Resolve and Resolve and Close. Selecting a workflow action switches the Detail pane into edit
mode.
4. Before updating the Work Item you may wish to add a comment, attach a file, or create a link to a
repository revision. After making any desired edits, finish the resolution process by clicking Save.
When you resolve a Work Item (for example, a Task, Change Request, or Defect), it can be highly useful for
your development organization if you link the resolved Work Item to the repository revision that contains
the code that implemented the feature or fix specified in the Work Item. Doing this consistently provides
the organization the possibility to trace development from a requirement, through process and changes, to
the source code. Aggregations of this kind of data can reveal flaws in the process which can subsequently
be corrected to improve the overall quality of development.
The best time to link a Work Item to a revision is when your resolve the Work Item. However, you can
create the link any time. If more than one revision contains code that resolves the Work Item, you can link
to multiple revisions.
You can create a link to a source code revision in the Linked Revisions section in the Work Item's detail
in the Table view. You can quickly navigate to the Linked Revisions section using the Links button in
the detail pane toolbar. Click the Edit link at the lower left of the section to access the linking fields and
actions.
If you know the revision number, you can enter it directly in the Revision field. If you don't know it, you
can click the (Select Revision) icon next to the Revision field and select one or more revisions in the
Revision Picker dialog. This dialog box has its own search tool that enables you to locate the desired
revision. The Revision Picker contains a preview area. When you click on any of the revisions shown, the
preview area displays the changed items in the selected revision.
If your project has been configured to support revision linking from more than one repository, the Linked
Revisions section contains a drop-down list from which you can select the repository before selecting the
revision. For example, a project might have source code in both Polarion's default Subversion repository,
and an external GIT repository. (For more information on this capability, see Using External Repositories.)
With the Work Item detail in Edit mode, you can add or create multiple revision links, or remove an
existing link.
If you link a Work Item to some revision of another Work Item other than the Head revision, the link is
considered "pinned". If the link is followed and the revision of the Work Item viewed, then some aspects of
the Work Item are different than if the link were to the Head revision. Specifically:
• The Actions menu contains only the Print option. Only the state of the Work Item in the revision
will be reflected in the printed output.
• The toolbar of the Work Item Editor displays the Show Current button. Clicking this button switches to
the Head revision of the Work Item.
• The browser status bar displays information about the revision when the pointer hovers over the
title (Date-time when the item was created and last revised, and the revision number). This same
information appears when the pointer hovers over a link to the revision in any Work Item.
• URLs of linked Work Items point to the same revision as the item being viewed, unless they are linked
explicitly to some other revision.
• A clock icon ( ) appears to the left of the Work Item title to indicate that you are viewing a revision.
This same icon appears in links to the revision in any Work Item.
• Backlinks are not displayed.
• Calculated fields do not show any values.
Polarion can recognize Work Item IDs in Subversion commit messages, so you can automatically create a
link between a Work Item and a revision simply by including the ID in the commit message. If a commit
resolves more than one Work Item, you can include multiple IDs in the commit message and revision links
are created for all mentioned items.
Warning
If Work Items in different projects have the same prefix, Work Items may not get linked correctly if only
Work Item IDs are cited in commit messages. For example, if users who create different projects keep
the default prefix WI, then Work Items my not get linked to the right revision in the right project, thus
compromising traceability.
Unless you have reliable processes in place to ensure that all projects on your Polarion system always
have unique Work Item prefixes, the recommended best practice to ensure correct traceability is
to always cite [Project ID]/[Work Item ID] in commit messages. For example: project1/
WI-9999 rather than simply WI-9999. The project name shown in Navigation is often the same as the
project ID, but it could be different. If in doubt, check the project properties in Administration, or ask
your administrator.
The Work Item identifier must be separated from the rest of the message by a space, or characters: ()
(parentheses), [] (square brackets), ? (question mark), ! (exclamation mark), , (comma), . (period),
" (double straight quote), ' (single straight quote), or : (colon).
Links derived from Subversion commit messages are shown in the Linked Revisions section of the Work
Item Editor. If a link is incorrect as the result of a typo in the Work Item ID in the commit message, the
link can be removed by deleting the relevant row in the Linked Revisions table. If some revision is linked
to the Work Item both explicitly by adding it on the Work Item Editor, and also in a commit message,
then it is shown twice in the Linked Revisions section on Work Item Editor.
Commit message in subversion client (Work Automatic link in created Work Item
Item Properties) DPP-34920
Tip
If you accidentally specify the wrong Work Item ID in a commit message, resulting in an erroneous
revision link, you can manually remove the link. Navigate to the Work Item whose ID you specified by
mistake in the commit message, and in the Linked Revisions section of the detail form, use the icon
to remove the linked revision. You should then navigate to the correct Work Item and link the revision
manually, as previously described.
The erroneous Work Item ID is not removed from the Subversion commit message, so it's a good idea
to leave a comment in the Work Item erroneously referenced to explain what happened and what
measures you took to correct it.
This section covers several more features commonly accessed or used by developers:
• Builds,
• Tests,
• Source code and documentation.
Note
Availability in Polarion Requirements & Reviewer:
This feature is also available in Polarion Requirements, but it is hidden in the default configuration.
The topic can be shown in Navigation by changing the Navigation topics configuration. For more
information, see Configure Interface Views.
Scope(s): Project
In order to work with builds, you must have the necessary permissions set up by a Polarion administrator.
Permission levels are read, create (which allows you to start new builds), and download. You can access
project builds via the Builds topic. Click this topic to show builds listed in a table (at the top of the
page). You can sort the table on any column by clicking the column header. Selecting a build in the table
displays its detail in the Detail pane.
Build details include build status, build author (the person who started the build or the name of the
system user (default "polarion") in case of initiation by a scheduled Job, and links to the build log and base
directory.
If you have create permission for builds, you can start a new build by clicking the New icon in the Builds
table. If you are not sure if you have the necessary permissions, mouse over the button and a tool tip tells
you if you cannot start a build. When you click the button, a new job is created (which you can see in the
Monitor topic), and a new row appears in the Builds table (Builds topic). You can check the build status
using Refresh. Your user name appears in the Author column (and in any build notifications which may be
sent as a result of the build).
It is necessary to set up a build configuration for each project. This is done in the Administration
interface, in the Build topic and its subtopics. You need to have administration rights for the project for
which you want to configure building.
Polarion provides summary information about testing, which you can access this information via the
Reports topic.
You can see the source code for any class (for the application or tests) in the current Project and access its
Javadoc™ documentation without leaving the web interface. Source code is read-only.
Procedure
Procedure
Polarion features that support quality assurance and testing activities include:
• Project templates: Preconfigured for test management projects, templates include Work Item types to
support testing. They provide for easy linking of test case and requirements artifacts for traceability
and impact analysis. As with all project templates, templates with test management support can be
customized and/or reused with modifications and customizations, after which users can create projects
that have the desired custom attributes as defaults.
• Test Specification: Enables import of existing testing assets and artifacts from Microsoft Excel or Word
as well as creation of new testing artifacts. Choose a Document based approach, or a tool based
approach, or a combination of both.
• Test Execution and Automation: Create Test Runs comprised of references to sets of test cases
(manual or automated). Execute Test Runs manually or automatically, integrating JUnit tests with the
Polarion Build system. Create Test Runs based on the default Test Run Templates, or derive custom Test
Run templates from these and create new Test Runs based on your derivative templates.
• Parametrized Testing: Define Test Parameters in Test Cases, Test Runs, and Test Run Templates that
enable an abstract approach to test specifications and efficient running of multiple testing scenarios
when executing Test Cases.
• Tip
You can gather helpful testing information using SQL queries.
◦ Fetch records via test parameters
◦ Fetch records via Test Steps and their results
◦ Fetch Documents by their signature status
◦ Fetch Work Item via parameters within Test Steps
◦ Fetch record via Test Record custom fields (like time and date)
• Integrate with External Testing: Execute testing either manually or automatically. Import results
of external testing. You can import manually as needed or automatically import results of external
automated tests exported to the xUnit framework's XML format for test results. (xUnit export is
supported by many third-party automated testing tools). Automatically create Work Items of the Defect
type for developers when tests fail.
• Workflow and Electronic Signatures: Configure the system and/or projects with workflow control for
Test Runs. Transition actions can be configured to require U.S. 21 CFR Part 11 compliant electronic
signatures.
• Excel Round-trip: (Optional) Use the Round-trip for Microsoft Excel feature to export Test Cases for
external manual testing and re-import test results stored in the Excel file, automatically creating Defect
type of Work Items for developers for failed tests.
• Reporting: Configure standard dashboards and use dedicated macros in custom wiki pages to create
dedicated testing/QA report pages for testing status and results.
Polarion users of licenses that provide access to quality assurance (QA) and testing features may want to
use project templates that provide support for creating, managing, and executing test cases. The project
templates are preconfigured to provide Work Item types, link roles, and workflows that support QA and
testing. Some project templates may also provide support for defining and managing requirements so that
these requirements may be easily linked to the test cases that verify them.
This section introduces the standard project templates that include QA and testing support. For a complete
listing of project templates with more detailed description, see Default Project Templates.
Project Templates
The best way to become familiar with these project templates is to work with a Polarion administrator to
set up a sandbox folder in the repository in which you can create experimental projects from the different
templates with quality assurance (QA) and test management support. (For a list of the default project
templates, see Project Templates.) Your administrator may give you permissions to create projects in this
folder, or you may have to work with the administrator to actually create your experimental projects in the
sandbox depending on your administration policy.
The procedure for creating projects is described in Project Administration. In your sandbox area, try
creating a project with each of the foregoing project templates, selecting them on the relevant new project
wizard screen. You need to be using a license that provides the template(s) you wish to try. You can always
download an evaluation copy of Polarion to try the various project templates, as the evaluation license
provides all of them. Remember too that any of the default project templates can be customized or have
copies created which can be customized to suit your exact needs.
See also:
A project based on the QA Project Template has a space named Testing (under Documents and Pages
in Navigation) which contains the following:
• Document: Test Specification. This is a placeholder Document that you can optionally use to write up
test case specifications. You can mark portions of the content as Work Items of Test Case type which are
then tracked in the tracker and managed with the project's workflow.
For information on working with Documents, see Documents and Pages.
• Page: Test Case Traceability. This page is a comprehensive report that shows which Requirements have
and do not have linked Test Cases.
Process Overview
Templates
This topic provides reference information on different types of templates used in Polarion.
Project templates
Note
Anyone who can create a project can select from the list of existing templates, but only administrators
can access the Project templates section where they can upload their own.
For more information on the different project templates, see Project Templates overview.
2. Click Administration.
We provide both empty and demo data versions of each of the templates. The demo data versions contain
the sample Documents, Work Items and the additional data you need to test drive the workflow and get a
jump on setting up your own projects.
See the Default Project Templates table below for details on each template.
The default project templates are stored in your Polarion installation in polarion/plugins/
com.polarion.alm.projects_x.x.x/templates (where x.x.x are numbers). Folders under this one
contain the default project templates distributed with Polarion.
In 2017 our templates were rebuilt from the ground up using our LiveReport™ technology. This lets users
make use of our growing library of report widgets like the drag and drop Work Items Board.
Long-time users of Polarion can still download our Classic Wiki Project Templates and Plan Macros are
still supported.
When selecting a new template in the Create New Project dialog, keep in mind that your system may be
configured with custom project templates, or you don't have an ALM license, so you may only have some
of the templates described in the table below.
Tip
You can find more project templates on the Polarion Extensions portal at https://
extensions.polarion.com.
Formatting of Excel Round-trip output is controlled by an export template. Polarion provides the following
export templates by default:
The default export templates are accessible in Administration Work Items Export
Templates xlsx: Microsoft Excel Round-trip Document.
See: Customizing Export Templates for additional information on customizing export templates.
Your ability to access and execute Test Runs depends on the permissions assigned to your user account,
which are normally tied to the user role or roles assigned to you by the system or project administrator. The
license you are currently using may also affect your ability to use some test management features.
You must have the following permissions in order to perform manual Test Runs:
• Permission to EXECUTE - You must have this permission for Test Runs in order to be able to execute a
manual Test Run.
• Because Test Runs can read, create and modify Work Items, you must also have the following
permissions for Work Items in addition to the EXECUTE permission for Test Runs:
◦ Permission to READ
◦ Permission to MODIFY
◦ Permission to CREATE NEW
The TEST_RECORDS keyword, with parameters, can be used in the Work Items Table view to search
for Work Items such as test cases, or defects, according to Test Records — to find items matching such
descriptions as "failed test cases executed by me in last week", or "defects triggered by test cases", to cite
just two of many possible examples.. It bypasses the usual Lucene query engine and queries the index of
the SQL database layer.
Tip
You can gather helpful testing information using SQL queries.
testrunId The ID of a Test Run, qualified with the ID of a project. For example: PRJ1/TR-200
result An option from the Result enumeration (configured in Administration Testing).
Accepts wildcard '*' (meaning 'any').
executedBy The ID of a user who ran the Test Run. Accepts wildcard * (meaning "any").
executed Time frame of the Test Run execution. Can be a single date or date range. Accepts
wildcard '*' (meaning 'any').
Examples
TEST_RECORDS:(proj1/testRun1)
The following table shows several examples for the TEST_RECORDS filter.
Example Notes
TEST_RECORDS:("myProject/ Finds all failed test cases in Test Run Smoke21
Smoke21","failed")
TEST_RECORDS:("myProject/ Finds all Defects linked from failed test records for Test
Smoke22","failed",*,*,true) Run Smoke22
TEST_RECORDS:("myProject/ Finds all test cases of Test Run Smoke23 that were
Smoke23",*,"johnd","20190702 TO executed by user johnd on 2nd or 3rd July, 2019
20190703")
Note
The TEST_RECORDS filter may be used as a subquery inside another query. For example:
Here is an example of an xUnit file showing only the tags and attributes read by Polarion.
</failure>
</testcase>
<testcase name="otherMethod" classname="OtherClass" time="0.002">
<error message="error message" type="package.OtherException">
Error Details
</error>
</testcase>
</testsuite>
</testsuites>
Job example
The xUnitFileImport job lets you import the results of externally executed tests into Polarion and creates a
new Test Run in the process. You can customize this process with the parameters below. You can also use
parameters when importing test results during Maven builds.
Note
If the xUnitFileImport job determines that Test Run IDs contain forbidden characters (via the
IdPrefix and idRegex job parameters), it replaces them with "_".
xUnitFileImport Parameters
Name Description
path Required. Path to the xUnit file, or to a folder containing xUnit files. (All XML files
are imported and then deleted.)
project Required. The ID of the project that the job will create Test Case and Defect Work
Items as output in.
idPrefix Prefix for the ID (composed of prefix+timestamp) of the Test Run created as
output of the job.
userAccountVau Reference to user authentication key contained in the User Account Vault in
ltKey
Administration User Management User Account Vault
maxCreatedDefe The number of failed tests before a summary Defect type Work Item is created
cts instead of individual Defect items for every failed test. (The default is 20.)
maxCreatedDefe The percentage of tests that can fail before a summary Defect type Work Item is
ctsPercent created instead of individual Defect items for every failed test. (The default is 10%.)
templateTestRu ID of the template Test Run that the Test Run created by the job is based on. The
nId template Test Run must exist in the project specified in the project parameter.
templateTestCa ID of the Test Case Work Item template used as the basis for the Test Case items
seId created by the job. The Test Case template must exist in the project specified in the
project parameter.
templateDefect ID of the Defect Work Item template used as the basis for Defect items created
Id by the job. The Defect template must exist in the project specified in the project
parameter.
idRegex Fills in the ID of the created Test Run with a regex matching the xUnit file name.
groupIdRegex Fills in the group.id of the created Test Run with a regex matching the xUnit
filename.
field[N] Replace [N] with a number between 1 and 3. Specify up to three fields that can be
additionally filled in with a regex matching xUnit file name.
field[N]Regex Replace [N] with a number between 1 and 3. When field[N] is specified, use this
parameter to fill in Test Run field[N] with a regex matching xUnit file name.
See the Monitor Topic and Configuring the Scheduler for more information.
Test results may be imported to a created Test Run during Maven builds by configuration in .polarion/
builder/build.properties.
The parameters are identical to the parameters for the xUnitFileImport job, except that all must be
prefixed with polarion.build.xUnit.import.
Unlike the xUnitFileImport job, however, xUnit files are not deleted after import.
The following parameters must also be specified in the Maven build configuration:
Parameter Description
polarion.build.xUnit.i Set to true to enable import of test results during the Maven build
mport.enabled process.
polarion.build.xUnit.i When import is enabled, specified the relative path to
mport.path=custom/path artifactId\target\surefire-reports in the job's working
directory.
polarion.build.xUnit.i Set to true to import all xUnit files to a single Test Run. Set false to
mport.singleTestRun import different xUnit files to separate Test Runs.
In Polarion, specifications for individual tests are broken down into Test Case Work Items. Test cases may
be aggregated in a Document or created individually in the integrated tracker. With either approach, the
test cases are managed with the project's workflow through each step of your process. You can import
existing Test Cases you have written in Microsoft Office documents, or you can author them using Polarion
tools.
Tip
You can gather helpful testing information using SQL queries.
Once you have Test-Case-type Work Items created, you can link them for traceability. You can link Test
Cases to other Test Cases, to Work Items of the Requirement type verified by the Test Cases, and to
Work Items of the Defect type that you may create during testing, or any other way to create exactly the
traceability you need.
If you have test cases written in Microsoft Word or Microsoft Excel, you can import existing documents
to Polarion, creating Test-Case type artifacts in projects which can then be tracked and managed with
project workflows. If you import from Microsoft Word, you create a new LiveDoc document, creating
Test-Case-type Work Items according to rules you set up to recognize such artifacts from the original
document content. If you import from Microsoft Excel, you can import in two ways. If you prefer a
document-based approach, import into a LiveDoc Document. If you prefer a tool-based approach, import
into the integrated tracker.
For more detailed information on importing information to create Work Items, see Import Work Items.
You may want to specify data in an Excel worksheet to be imported into multivalued fields in Polarion. For
example, the Category field can contain multiple values. Your project might also have some multivalued
custom fields. If properly formatted in the Excel sheet, the Polarion importer recognizes multiple values
and imports them correctly. You can format multiple values in two ways:
• Specify each value in a cell under the column for the field, and merge that column to span all the values.
• Specify all values in a single cell under the column for the field, separating each value with a comma
character.
You have two alternatives for formatting Excel data for import to Polarion multivalued fields
Recognition of multivalued data can be switched on or off in the import wizard using the Separate multiple
values option. When this option is selected, delimited values in a mapped column are imported to Polarion
as multiple values in the target field. Recognized delimiters are comma (,) and semi-colon (;) characters.
Detection of merged heading cells in Excel is automatic.
For reference information on supported fields, see Multivalued Data and Fields.
When defining Test Cases having discreet test steps, you can format your Excel worksheet in such a way as
to facilitate import into Polarion. Here are a few tips:
• Specify a column with a name like Title to identify each Test Case. You can include another column such
as Description for the general description of each Test Case.
• Define columns corresponding to those defined in your projects Test Step Columns configuration, for
example, Step Name, Step Instruction, Expected Result.
• Use one row for each step when writing up the test steps. Then, when these are complete, vertically
merge the Title and Description columns so that they encompass the test step rows (see figure below).
You may wish to leave an empty row between test cases. This can give you an additional import rule
condition when importing your test cases.
When you import the Excel workbook, you can map test steps to the Test Steps field of Test Cases. For more
information on importing from Excel and mapping columns to fields, see Import from Excel.
The following sections discuss creating new Work Items in existing Documents and the Work Item Tracker.
Limitations
Avoid using the same Names with different IDs (or the other way around) in a single Project. You may lose
data from those columns during Excel Round-trip. You can reuse columns with the same Name and ID.
We identified the following issues regarding Test Steps used in Excel Round-trip:
• For columns with the same Names but different IDs, only one column per Name is exported to Excel.
• For columns with the same IDs but different Names, the columns might not be sorted properly in the
exported Excel file.
• For columns with the same Name in Excel, only the last column is imported to Polarion.
• All of these issues apply for IDs and Names of any Custom Field as well.
Polarion's LiveDoc Documents (Documents) are often preferred for defining test cases by teams who are
accustomed to work with document-based test case specifications. Content in Documents can be marked
as Work Items of the Test Case type. They can then be tracked and managed with project workflow, yet still
appear as content in a document.
When you create a Document for specifying test cases, be sure to select Test Case as the Work Item type
the new Document should contain. If you accidentally select a different type or you want to have multiple
Work Item types in the Document, you can configure the Document after it is created.
To learn all about how to work with Documents, review Documents and Pages Topic.
Tip
Projects can be configured by an administrator to include a table of manual test steps in Work Items of
the Test Case type. When Test Steps support is enabled, discrete test steps can be defined in this special
Test Steps field. The results of individual test steps can then be logged when testers execute manual
tests.
When configured this way, the Document's Work Item presentation displays the Test Steps table in Work
Items. Rows can be added to the table using the Add Row button, which appears when the cursor is
located inside the test steps table when the Description field is in Edit mode.
If you do not see the Test Steps in Test Case items in a Document, it is possible that another user
changed the Work Item presentation to some setting that does not display test steps. To show the Test
Steps table in Document-based Work Items, you can set the Document's Work Item Presentation. Click
the drop-down control beside the Work Item icon in the Document Editor toolbar, and on the menu
choose Configure. In the dialog box, select one of the options that includes Test Steps.
For more information, see Executing a Test Run and Enabling Manual Test Steps.
You can use the Round-trip for Microsoft Word feature to export test specification Documents to Word for
review, comment, and collaboration. For more information, see Share Documents Using Word Round-
trip.
You should note the following when exporting test specification Documents containing Test Steps in Test
Cases:
• A Document that is configured to show Title, Description, and Test Steps, or Title and Test Steps can be
exported for Review, Prioritization, or Collaboration.
• When exported for Review or Prioritization, the Test Steps can be commented. Comments are written to
the Description field upon re-import to Polarion.
• The content of test steps cannot be edited in the exported file.
If your team prefers a tool-based approach to defining test cases, you can create Work Items of the Test
Case type directly in the integrated Work Item tracker. If your project is based on one of the standard
Polarion project templates with QA and testing support, the Test Case type is preconfigured. If your
project's configuration is customized, the Work Item type corresponding to a test case may have a different
name, which you should substitute for "Test Case" in the procedure that follows.
Procedure
1. Log on and open the relevant project. Your user permissions for the project must allow you to create
new Work Items.
3. On the toolbar of the Work Items page, click the icon and choose Test Case in the
drop-down menu. A new, empty form appears in the Work Item Editor pane of the page.
(You cannot create new Work Items in the Matrix and Time Sheet views.)
4. Fill in the fields, supplying a value for all required fields. Optionally create links to other Work Items,
specify hyperlinks to relevant resources, and add attachments.
In the default configuration of projects based on a Polarion project template that provides QA and testing
support, test case Work Items can be linked to each other and to other Work Item types such as defects
or requirements. Linking is vital for future traceability and impact analysis. You can link items to others in
the same project or in different project. In systems configured for multiple concurrent Polarion servers, it is
possible to link to items residing on a different server, but the linking is not as robust as when items are
linked within or across projects residing on the same server.
• Linking Test Case items to Requirement items with a "verifies/is-verified-by" link role (relationship).
• Linking Defect items to Test Case items with an "is-triggered-by/triggers" link role (relationship). When
using test execution features of Polarion's QA and testing project templates, Defect items with such link
roles are created automatically upon failure of tests.
• Any failure can be linked and easily traced to the test step in which it occurred.
• Test Steps data is separated from the Description field, which can be then reserved for general
information about the Test Case.
• If a Test Run is exported to Excel for manual execution of tests offline, only test step and results data are
involved in the round-trip. Other Test Case data, such as the Description, cannot be modified by external
testers.
Your project administrator can then enable the specification of manual test steps in the project
configuration.
When correctly configured, a table of test steps appears in the Custom Fields section of new Test Case
items (unless the administrator opted to display the table separately). Testers can specify each test step
as a row in the Test Steps table. The table is rendered as executable test steps. Test Steps appear when
the Test Case is executed during a Test Run. As shown in the picture above, Testers can log the results of
individual test steps when the Test Case is executed during a Test Run.
When Test Steps are enabled in your project, they are a field of your Test Case type of Work Items, so the
steps can be edited in Test Cases defined in Documents. You need to set the Presentation Configuration in
the Document, selecting either Title and Test Steps or Title, Description and Test Steps in the Content
column of the Configure Work Item Presentation dialog box. See Multiple Work Item Types for more
information on this dialog box.
Test Runs log instances of the running or performance of a defined set of Test Cases. Test Runs may
log results of manual tests or automated tests run as part of a build. Test Runs also contain information
about the status of the Test Run, results of the instance of testing that the Test Run represents, the test
environment, and the build tested.
An individual Test Run is based on a Test Run Template. Polarion comes with several predefined
templates, which can be customized or used as the basis for custom Test Run Templates.
Test Run Templates can save a great deal of time in the long run. You configure the properties of the
template once, and then all Test Runs based on the template are preconfigured with the same properties.
(Some of which Test Run creators can modify in Test Runs based on the template.)
• A Test Run Template is essentially a Test Run, with configurable properties and Page design.
• The main difference is that a template itself cannot be executed. Only Test Runs created from it can be
executed.
So your goal in customizing a Test Run Template is to set it up exactly as if it were a Test Run.
You can customize an existing Test Run Template by modifying the Test Run Properties, or by modifying
the underlying Widgets on the Test Run Page.
Tip
For some Test Case selection strategies you can select Test Cases from multiple Projects via the
Project Span field.
Procedure
1. Open the Project containing the Test Cases you want to test with Test Runs.
(For some Test Case selection strategies you can select Test Cases from multiple Projects.)
Tip
Click to filter the Test Run Templates listed.
Any existing Test Run Template or Test Run can serve as the basis for a Test Run Template.
Tip
If you want to customize one of Polarion's default Test Run Templates, always create a duplicate and
customize it so you do not accidentally corrupt the default template.
Procedure
(So you do not accidentally corrupt the default template when customizing.)
Procedure
(For some Test Case selection strategies you can select Test Cases from multiple Projects.)
2. Click and select Duplicate Template or Save as Template. The text of the menu item
depends on the Polarion version you are using, and/or the type of the template's page: Document
or Classic Wiki.
3. In the dialog box, provide a unique ID for the new Test Run Template and a human-friendly title, and
then click Duplicate Test Run Template.
After creating the duplicate Test Run Template, you can proceed to modify it as described in the next
sections. If workflow is configured for the Test Run type, the Duplicate Template action resets the
Status to the configured initial Status, and invokes the configured initial workflow action, if any.
Test Run Properties include such data as Test Run type, testing platform and environment, and Test
Parameters. Every Test Run created using the modified Test Run Template will have the properties and
values as specified in the template. A simple graphical user interface is provided for editing the template
properties.
Procedure
(For some Test Case selection strategies you can select Test Cases from multiple Projects.)
2. Select a Test Run Template in the table of templates.
4. You can now edit some property fields, but click Edit to place all non-read only fields into edit
mode.
The values for some properties like Test Type are defined in the Global or Project Testing
configuration in Administration. You can select from configured values, but you cannot change the
values themselves. For more information, see Configure Testing.
In a Test Run Template, the Status field is not editable if a workflow configuration for Test Runs
exists.
In the Test Run Template's Properties, it is important to specify the method you want to use to
populate new Test Runs with the Test Cases you want to execute. You do this by setting a value for the
Select Test Cases field.
• Manually:
Creators of new Test Runs based on the template can manually select the Test Cases to execute, or
the Test Cases can be manually selected by the author of the Test Run template. (They are preselected
when a new Test Run is created from the template.)
• By Query on Create:
Test Cases are selected by a query that automatically runs when a new Test Run based on the template
is created. The set of Waiting Test Cases of the Test Run is static and does not change if new Test
Cases that meet the query criteria are added after a Test Run is created, but before it is executed. Nor
will any be added to the set if the Test Run is executed multiple times, even if new Test Cases that
would meet the criteria were added in the system since the last execution of the Test Run.
When you select By Query on Create you must specify Lucene query syntax items in the Query
field that will select the Test Cases that testers must execute in Test Runs based on the Template. You
must specify this query before you can save changes to the Template.
Note
Click to add Projects in the Project Span field.
◦ If you only need to select Test Cases from the current Project, you can leave this field empty.
◦ If you want to select Test Cases defined in one or more different Projects, then specify them in
the Project Span field.
◦ If you also want to select Test Cases from the current Project, then you must include it in the
Project Span field.
• By Query on Execute:
Test Cases for Test Runs are selected by a query that automatically runs when a Test Run based on
the template is executed. The set of Test Cases waiting to be executed is not static. Waiting Test Cases
are taken from the current set of Test Cases in the system meeting the query criteria at the time a user
executes the Test Run, and could even change during the execution each time the view refreshes.
When you select this option you must specify Lucene query syntax items in the Query field that will
select the Test Cases that testers must execute in Test Runs based on the Template.
You must specify this query before you can save changes to the Template.
When By Query on Execute is selected the multivalued field Project Span appears.
Note
Click to add Projects in the Project Span field.
◦ If you only need to select Test Cases from the current Project, you can leave this field empty.
◦ If you want to select Test Cases defined in one or more different Projects, then specify them in
the Project Span field.
◦ If you also want to select Test Cases from the current Project, then you must include it in the
Project Span field.
If you only need to select Test Cases from the current project, you can leave that field empty.
The query entered in the Query field should be valid for all specified projects, otherwise some desired
Test Cases may not be added to the Test Run, or some Test Cases may be added that are not relevant.
For example, if you specify a query like (type:testcase AND status:active AND testType:
(manual user)), but in one of the Projects the test type is configured as manual ui and not
manual user, Test Cases from that Project are not added to your Test Run.
Caution
For By Query on Execute or From LiveDoc on Execute selection types. (Dynamic Test Runs):
◦ When closing dynamic Test Runs by setting a previously unset finished date, usually by a workflow
action, the number of Waiting Test Cases gets stored in the Test Run as empty Test Records and
no longer changes.
◦ When reopening a dynamic Test Run, by clearing a previously set "Finished On" date – usually
also by a workflow action, the number of Waiting Test Cases becomes live again and corresponds
to the current number of unexecuted Test Cases matching the Test Run query.
◦ The query to retrieve or count awaiting Test Cases will therefore differ for finished and unfinished
dynamic Test Runs.
All Test Cases contained in the specified Document are selected for execution when a new Test Run
based on the template is created. The set of Waiting Test Cases of the Test Run is static and does not
change if new Test Cases are added to the Document after a Test Run is created, but before it is
executed. Nor will any be added to the set if the Test Run is executed multiple times.
Specify the Document in the required Document field of the Test Run Template properties. Select a
Document from the drop-down menu. Preview it by clicking on the icon beside it, or just start typing
a word contained within the Document's name. Documents located outside the default Space will
include the Space name before it. (Separated by a "/"). You can optionally specify a query in the
Query field to select a subset of the Test Cases contained in the specified Document. For example, you
might query for Test Cases with a Status value that is not Draft, such as NOT status:draft.
If the list of Documents is extensive and covers several Spaces, just type the Space name. Only
Documents within that Space are listed.
◦ When using From LiveDoc on Create, you can also select Test Cases from a specific Document
revision.
If you enter a revision number the Test Run uses the Test Cases as they are written in that version
of the Document.
Example
◊ You have a product with multiple versions, and the Test Cases in your Test Runs have been
evolving along with your product.
◊ Version 1 of your product is still in use, and you need to test it with the Test Cases in
the associated Document revision because newer Document revisions contain Test Cases for
features that do not exist in Version 1 and will fail.
Limitation: You can only select historical revisions for the From LiveDoc on Create strategy
and cannot choose a revision when manually selecting Test Cases.
Referenced Test Case items can be from Projects other than the Test Run and the specified
Document, or frozen to a particular revision of the referenced Test Case, or both.
Specify the Document in the required Document field of the Test Run Template properties. (See From
LiveDoc on Create for the drop-down box's behavior.) You can optionally specify a query in the
Query field to select a subset of the Test Cases contained in the specified Document. For example,
for a Smoke test, you might query for open manual type Test Cases, like status:open AND type:
manual.
• Automation:
Test Runs based on the template are created by an automated process and test execution results are
imported to Polarion.
Test Runs and Test Run Templates are Live Report Pages. You can use the full range of editing
features and Widgets to customize the layout and content of a Test Run Template.
Caution
Before you modify an existing Test Run Template, you should create a duplicate first, make all of your
modifications and test the Page before applying the same changes to a Test Run Template.
Procedure
Tip
Administrators can configure Quick Create so users can create a Test Run right from the Navigation
Header.
Procedure
1. In Navigation, click Test Runs. The Test Runs page loads displaying a table of existing Test Runs.
2. In the toolbar of the Test Run table, click New to launch the Create Test Run dialog box.
The values in the properties of a Test Run are inherited from the Test Run template from which it is
derived. If you have the necessary permissions, you can modify a Test Run's properties. For example, if the
template specifies one or more projects from which Test Cases can be selected in the Project Span field,
then for a particular Test Run you can either modify the project selection or clear the field entirely so that
Test Cases can only be selected from the current project.
Procedure
1. Select the Test Run in the table at the top of the Test Runs page.
If a newly created Test Run is based on a Test Run Template that is configured for the manual selection of
Test Cases, you must manually select the Test Cases before you or others execute the Test Run.
Tip
You can manually add Test Cases to Test Runs in two ways:
See Specify Test Case Selection for details on the different strategies that automatically populate Test
Runs with Test Cases.
Default Test Run Templates that support manually selecting Test Cases out-of-the-box:
• Empty
• Software Verification Test
• System Verification Test
Test Cases can be defined in the current project and/or in one or more other projects. For example, a
project named Standard Tests might define a set of Test Cases that must always be tested for every
application, while the current project contains Test Cases specific to an application or variant.
Tip
• To select Test Cases from multiple projects, you must add the projects in the Project Span field.
(You must also include the current project)
• If all Test Cases are only in the current project, you can leave Project Span empty.
Prerequisites
Procedure
• Select Test Cases only appears if manual selection of Test Cases is allowed by Test Run
strategy.
• Test Cases appear in Table view and the Test Run Planning sidebar appears on the right.
• You can modify what Test Cases that appear in the table by changing the query above it.
5. Select a Test Case and click to the left of the table or Add in the Test Run Planning sidebar.
(Click in the table or Test Run Planning sidebar to remove selected Test Cases.)
Tip
Add / Remove multiple Test Cases at once:
a. Click on the selection box for any Test Case that you want to add or remove.
b. Click Add or Remove them in the Test Run Planning sidebar
.
• The sidebar updates to show the total number of Test Case executions Waiting.
• If some Test Cases have multiple Iterations defined for the current Test Run, these are reflected in
the Waiting count, which may then be larger than the number of items selected in the table.
• Added Waitingitems are highlighted in blue at their left border.
6. Repeat this for all the Test Cases you want to include in the Test Run.
7. Click Save Test Run in the Test Run Planning sidebar.
Tip
• You can quickly switch to another Test Run by selecting it from the Test Run Planning sidebar.
• Some of the Test Runs listed may not be configured for manual Test Step selection.
(If you select one that's not, a warning message appears.)
• The Navigation scope can change depending on the setting in the Test Run's Project Span
property. If multiple projects are specified there, the scope switches to Repository. If just one
project is specified, the scope switches to that project. If Project Span is empty, the scope
remains in the current project.
• To return to the Test Run after selecting Test Cases, regardless of current Navigation scope,
click the Test Run name in the Test Run Planning sidebar.
If not already open, the project containing the Test Run opens and the Test Run page loads in
the browser.
Prerequisites
Procedure
If the Test Run is configured for a single Document, the Document and the Test Run Planning
sidebar appear.
a. Click on the top right then Test Run Planning to open the Test Run Planning sidebar.
b. Go to Navigation, navigate to the Space with the Document that contains the Test Cases
you want to be select for the Test Run, and select that Document. The Document opens in
the Document Editor, and the Test Run Planning sidebar remains open.
c. (Optional) If the Navigation node contains too many Documents, you need to locate and
open the desired Document via the Space Index page or Search. After opening the
Document, open the Test Run Planning sidebar ( Test Run Planning).
Tip
• When a Document opens, it is filtered by a query built and run when you click Select Test
Cases. Modify the query and click Filter to increase or reduce the number of Work Items
displayed.
• You can also select Test Cases from a previous version (revision) of a Document.
6. You are now ready to add Test Cases from the Document to the Test Run.
7. Select a Test Case so that it's highlighted in blue and click in the margin or Add in the Test Run
Planning sidebar.
Tip
To add multiple Test Cases, select all of them (Shift + Click in most browsers), then click Add in
the Test Run Planning sidebar.
• Click in the margin or Remove in the Test Run Planning sidebar to remove Test Cases from
the Test Run.
• The count of waiting Test Case executions is incremented in the panel by the number of selected
items plus additional Iterations, if any. (Multiple items must be contiguous to be selected at once.)
8. Testers can now execute the Test Run by clicking the Execute Test button on the Test Run page.
Test managers may sometimes need to populate a Test Run with Test Case items from a specific version of
a test specification Document that has been reviewed and approved.
Procedure
1. Open the desired Document revision in the Document Editor. See View Document History.
2. With the revision open in the Document Editor, create a new branched Document ( Actions
Branch). See Branching Documents for more detailed information.
Example
• Suppose you have a Test Specification Document that is under continuous
development, and a Version 1.0 Plan that should be populated from revision 1001, has
been reviewed and approved for production.
• From Test Specification revision 1001 , you create a Branched Document named,
for example, Test Specification Version 1.0 - Frozen.
3. Create a new Test Run Template named, for example, Rev. 1001 Tests, selecting Empty as the
template base.
4. Set the Select Test Cases field to LiveDoc on Create, and in the Document drop-down box
specify the branched Document created in Step 2.
(Start typing the Document's name in the Document field and select it)
5. Click Save, and click Manage Templates to return to the Test Runs page.
6. Create a new Test Run based on the new Test Run Template you just created, Edit the properties
if necessary, and Save it.
When this Test Run is executed, the Test Cases are those from the branched Document that was
branched from Revision 1001 of the specification.
After creating the new Test Run (or at some other time if something changes before the Test Run is
executed), you may want to edit some Test Run properties such as the test environment or Test Run
Parameters. After selecting the Test Run you want to edit:
• If you are not already on the Test Runs page, click Test Runs in Navigation to access it. Then, in the
list of Test Runs, select the Test Run you want to edit. Optionally, use the Visual Query Builder at the top
of the page to filter the list of Test Runs. For example, you might query for Manual type tests based on
a specific Test Run Template. For more information on the visual query builder tool, see Searching Work
Items.
• Selecting a Test Run in the table at the top of the page.
• If you want to edit the Test Run's properties, click Properties. If any fields of a Test Run are configured
as required fields, a red asterisk appears and the field must be filled before you can save the Test Run
properties.
• If you want to modify the Test Run's page, for example the layout, click Actions and select
Customize Test Run Page.
Tip
When hovering over the Smart Title of a Test Run in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Test Run link with its ID and Title as the link's label.
You can attach any type of file to a Test Run, either while in the process of creating it, or later on when
logging the result. For example, you might attach a file containing test result output from some external
testing tool. To add or manage attachments, click (Attachments) on the Test Run toolbar to scroll the
page to the Attachments field.
If your system is configured to support searching on attachment properties and content, you can search on
properties of Test Run attachments. In the Test Runs topic of Navigation, you can search on attachment
title, attachment author ID or name, attachment file name, content, date updated, and size.
In site search in Navigation, you can search attachments to Test Runs via full-text search.
Warning
Thinking of using Classic Test Execution View instead? Don't.
It is disabled by default, no longer tested, scheduled for removal, and may even affect performance!
As previously mentioned, a Test Run represents an instance of executing a set of test cases, which have
been defined in Work Items of the Test Case type. At some point after a Test Run is created, a tester
manually performs the testing steps defined in the Test Cases of the Test Run. During the actual execution,
the result of each testing step is recorded, as is the outcome or "verdict" of each Test Case (passed, failed,
or blocked).
Even if you use some external tool to execute Test Cases, testers can still execute a Test Run to log the
results of external testing so that testing history and traceability are maintained in Polarion across the full
life cycle.
Tip
• You or another user may modify a Test Case or Test Steps while test execution is Paused.
If this happens, the Resume Test Case dialog box appears with a warning after selecting Resume.
• If a Test Case is modified before you Correct or Retest it, warnings also appear.
Each warning tells you that the Test Case was updated while you had it open, but each action behaves a
little differently when you choose to Continue.
• Resume Test Case: The Test Case and Test Steps remain the same, and you continue testing the
version you started with.
• Correct Test Case: The Test Case and Test Steps remain the same, and you edit the version you
started with.
• Retest Test Case: The Test Case reloads, and you retest the latest version of the Test Case that differs
from what you started with.
Procedure
1. Open the Test Run's page by clicking Test Runs in Navigation, and selecting the Test Run in the
table of Test Runs. You can use the visual query builder on the Test Runs page to filter a large number
of Test Runs. For example, you might query for only Manual type tests, based on a specific Test Run
Template.
The Outline Number column appears if the document referred to by the Test Run has Outline
Numbering turned on.
• Refreshes the table and/or Test Case. The top refreshes both.
When a Test Case is modified (executed/restarted/or paused), the columns and the Test Run
statuses ("Waiting", "Executed" etc.) are refreshed automatically.
• Next Skips items that can't be executed and jumps directly to the next executable Test Case.
• Cycle through all items, including those that can't be executed, such as Headers.
• Launches a table of your queried results where you can add or remove Test Cases, if the Test
Run type allows it.
• Define Auto Advance and Auto Start the next Test Case Execution Settings.
5. (Optional) Click , and then Tile Panes Vertically to display the table and selected Test Case
side by side.
(Or Tile Panes Horizontally to return to the default, table over the Test Case, view.)
6. Use the query builder above the table to search for individual Test Cases or sort by things like
Severity.
You cannot set a default query, but you can easily save them for quick reuse.
You can also quickly narrow down what Test Cases appear by clicking on a Status or Test Case result.
Click on a selected status or result a second time to remove the filter.
7. If a Test Run item is selected in the table that cannot be executed ( Headings, other Work Items
or Test Cases) an informational message appears below the table.
Note
Adding iterations directly into the execution view is not possible. They can only be added prior to
execution using the Select Test Cases command.
Note
Set Polarion to remember your table settings:
If you add or remove columns by right clicking and adding or removing a or sort columns by
clicking on them, your settings will be lost if the browser is refreshed.
For a persistent setup, click More, make your changes in the Customize Table dialog box, and then
click Apply.
10. Click More in the column context menu to launch the Customize Table dialog box. There you can
completely customize what columns are visible, how they are ordered and sorted, and even whether
or not to display icons in the columns that support them.
Add an Available Columns item that you Applied changes will only be saved for the
want to appear in the table. current user.
Set the column order. (Top is left.) Save and label a custom table
configuration.
Select how column data is sorted. Manage and select saved custom table
configurations.
• When you add a custom field ID, use the following syntax: testCase.fieldID.
Just the fieldID is fine for the Work Item table but not the Test Run table.
• When configuring sorting, the Test Record fields must precede any Test Case fields in significance.
• The Execute Test button widget supports a Sort Test Cases by parameter (for Test Runs
that are not defined by a LiveDoc), but it has no effect when using execution view. (It is used
in the Classic Test Execution View.) Instead administrators should define their desired default
configuration here in the Customize Table dialog box. (The default sorting configuration is
ascending by Test Case ID.)
• Administrators can also set repository wide Test Record table settings by editing the testrecord-
table-settings.xml in the repository.
(repo/.polarion/testing/configuration/testrecord-table-settings.xml)
11. (Optional) Send a custom link to what you are testing to another user.
a. Click on a Test Case in the table.
b. Hover over the Test Case's title below the table and click when it appears.
c. Click Copy Link to this Test Record.
d. The browser link is copied to your clipboard.
12. Click Next to jump to the next available Test Case in the table.
• If the selected Test Case was already started but Paused, Start will be replaced with
Resume.
• If the Test Case has been run but needs to be corrected or run again.
◦ Click Retest to clear the Test Record and start the test again.
If the Correct and Retest actions are disabled, hover over the button for a tooltip that
explains why.
14. The Test Case's Test Steps appear below and the timer begins or resumes.
• Click Save as Paused to pause and save Test Step without a verdict.
• You can enter and format rich text using the Document Editor toolbar and even add images
directly into the result field of the test step.
Caution
Limited rich text editing for offline test execution:
Offline test execution does not support the following rich text editor features:
• Images inside the text. (Like the example above.)
• Hyperlinks within the text.
• Tables within cells.
• Bullet lists.
These limitations also apply to the Excel Round-trip feature.
15. Click on a Test Step Verdict ( Passed, Failed or Blocked) and continue on to the next test step.
16. (Optional) Click Recent to select from a list of previously entered Test Step or Test Case verdict
comments.
The Recent menu displays comments from any Test Run (by any user), that contains the selected Test
Step or Verdict.
Comments from a previous iteration in the same Test Run are also included.
Note
The selectable comments support rich text formatting and offer an image preview, but only insert a
text placeholder for the images.
17. Below the final step you'll see a timer that displays the total Duration of the entire Test Case.
Tip
Administrators can also configure what appears in the section above the Test Steps.
20. With the default configuration, any Test Case Saved as Failed will automatically create a Defect
Work Item.
You can view Test Runs executed in a previous Project Baseline, but you cannot execute them.
However, the Waiting button can be used to see the last Test Cases that were waiting at that point in the
history and open the Test Run's execution view.
(Only for LiveReport based Test Runs created with the execution view implemented in Polarion 18.)
Empty Test Step values are omitted to save space and increase readability.
With the appropriate permissions, you can Delete Test Records from Polarion, but the behavior varies
depending on the Test Case strategy deployed. (How you chose to add Test Cases to a Test Run.)
• For dynamic strategies like By Query on Execute and From LiveDoc on Execute:
Delete removes the verdict, and the Test Case immediately reappears in the Test Run in the Waiting
state.
• For static strategies like By Query on Create, From LiveDoc on Create, Automation or
Manually:
Delete removes the verdict and the Test Case from the Test Run.
You must re-add the Test Case to the Test Run before you can execute it again. (This is not possible for
the Automation strategy.)
Note
• Administrators can restrict users from deleting Test Records via the following permission:
If this permission is not explicitly set, then the permissions set in Permission to MODIFY are
used.
• A deleted failed Test Record also removes the related row in the Problems Reported section at the
bottom of the Test Run page.
Procedure
Tip
• You can also click on the Waiting button on a Test Run to jump to a list of all pending Test
Cases.
• Click on the top left to toggle table visibility and the name of the Test Run to return to the
Test Run home page.
• You can filter the Test Cases by clicking on the buttons on the top right.
a. If you clicked Test Run Records, click on the Test Case that you want to delete the Test
Record for.
b. If you clicked on Waiting, select a Test Case you want to delete the Test Record for from the
list.
Tip
If Delete is disabled, hover over the button for more information.
You can edit Test Run Execution Settings so that Polarion automatically jumps to, and even starts the
next Test Case.
Procedure
1. Click at the top of the active Test Case, and select Execution Settings.
The Execution Settings dialog box appears. The settings in this dialog box apply to all Test Runs for
the current user.
2. Select or deselect the automatic execution options of your choice:
Auto Advance to the Next Automatically proceed to the next Test Case when the current result
Test Case is saved.
Auto Start the Next Test Automatically start the execution of the next Test Case.
Case
Tip
This option can only be selected when the previous option is
selected.
3. Click Save.
Your selection is saved and tied to your personal user preferences so that they are the same for all of
your Test Runs.
If your project is not configured for Test Steps or if a Test Case does not contain multiple steps in a Test
Steps table, then the panel in the lower section of a Test Case contains only the Test Case Verdict field and
buttons to mark the overall Test Case verdict as Passed, Failed, or Blocked.
Procedure
1. Click Start.
2. Perform all the necessary testing activity to determine the result of the Test Case.
Multiple Test Runs can be run simultaneously, even when they contain the same Test Cases.
Projects may be configured to require testers to electronically sign executed Test Cases. If your project is
so configured, then when you mark the Test Case Verdict, a dialog box displays requesting you to sign by
entering your user name and password. See also Signatures for Test Case Execution.
By default, any unresolved defect Work Item (or equivalent type) from any Iteration in the current Test
Run, or from any iterations in the previous Test Run (or the previous Test Run in the same group), is reused
for failures of the same test case if the test case failed in the most recent execution.
In Test Runs that use test cases from different projects, this works differently. A defect item can be reused
only if it is linked to a test record in a Test Run in the same project as the current Test Run. This also applies
to Failed in previous and Failed in group reuse strategies. For example, suppose Project A uses the defect
reuse strategy always. You execute a test case in a Test Run in this project, and it fails. The previous Test
Run in which the same test case was executed is in Project B. This previous execution failed, creating a
defect item that is not resolved yet. That defect, in Project B, is not reused. Rather, a new one is created in
the project specified in the testing configuration in Project A.
Procedure
1. Select a completed Test Run from the table of available Test Runs.
2. Click then Test Run Records. (Or, scroll down to the bottom of the page, and click
Browse All Test Run Records.)
3. The Test Run's Test Record list appears.
Warning
This feature is disabled by default, no longer tested, scheduled for removal, and may even affect
performance!
Recommendation: Use the improved Execute a Test Run Using Polarion workflow instead.
Procedure
3. Click Save.
4. Add com.siemens.polarion.ui.testExecution.oldExecutionView.enabled=true to
the polarion.properties file.
Execute a manual Test Run with the classic Test Execution view
Procedure
1. Open the Test Run's page by clicking on the Test Runs in Navigation, and selecting the Test Run in
the table of Test Runs. If there are many Test Runs, you can use the visual query builder on the Test
Runs page to build a query to filter the table. For example, you might query for only Manual type
tests, based on a specific Test Run Template.
2. Click Execute Test. The Work Items table opens in a new browser tab with the Test Cases selected by
the Test Run configuration listed in the table.
Tip
It is possible that another user could modify the Test Case or Test Steps while you have paused test
execution. If this happens, the Resume Test Case dialog box (if Test Case was revised) or Retest Test
Case dialog box (if Test Steps were revised) appears.
• Resume Test Case: Warns that you are no longer testing what was planned. For example, the Test
Case was planned from HEAD revision, and the Test Case subsequently was updated while the Test
Case was in progress. Or possibly, the revision in which the Test Case was planned changed (for
example, frozen to a different revision in a Test Run where Test Cases are selected via the LiveDoc on
Execute option). In both scenarios, after clicking Resume Test Case in the dialog box, the Test Steps
remain the same, and you continue working in the revision in which you started.
• Retest Test Case: Means that the Test Case (including the Test Steps) is updated and retesting needs
to be done in the new version. If you click Retest Test Case, the Test Case is reloaded and execution is
automatically started.
Procedure
Caution
If the Test Case's Description field contains a table containing Test Steps, while it's possible to
merge the cells in the table this not recommended.
It may render the Test Steps unusable.
3. Repeat the above for all Test Steps listed in the section.
4. If there are multiple Iterations of the Test Steps, continue testing until you have completed all steps
in all Iterations, or until something fails.
If there are untested Test Cases in the table, and the Open next queued Test when finished
option is selected, the next Test Case in the Test Run is automatically selected and ready for testing to
begin on that Test Case. As long as the option is checked, this happens until all Test Cases in the Test
Run are executed. In Test Cases with Iterations in the steps, the process proceeds through the Iterations
before moving on to the next Test Case. The statistics in the Test Run Planning sidebar update to reflect the
progress of the testing session.
Note
It is not required to mark results for any of the Test Steps. You can mark all, some, or none. You need
only log result of the Test Case: Passed, Failed or Blocked. However, Actual Result of every step is still
written to the test record even though the test step has no verdict.
Note
The Navigation scope can change depending on the setting in the Test Run's Project Span property. If
multiple projects are specified in that setting, the scope switches to Repository. If just one project is
specified, the scope switches to that project. If Project Span is empty, the scope remains in the current
project.
To return to the Test Run after selecting Test Cases, regardless of current Navigation scope, click on the
Test Run name in the Test Run Planning sidebar. If not already open, the project containing the Test Run
opens and the Test Run page loads in the browser.
If your project is not configured for Test Steps or if a Test Case does not contain multiple steps in a Test
Steps table, then the panel in the Execute Test section of a Test Case contains only the Test Case Verdict
field and buttons to mark the overall Test Case verdict of Passed, Failed, or Blocked. You can also add
attachments to the Test Case Verdict using the Add Attachment link in the panel.
If the Execute Test panel does not have individual Test Steps:
Procedure
is automatically selected and ready for testing to begin on that Test Case. As long as the option is
selected, this happens until all Test Cases in the Test Run are executed.
It is possible to execute a Test Case that has not been selected in a Test Run (That is, it has not been
planned for execution in a Test Run). When the Test Case item is open and selected in the Work Items
table, you can select a Test Run via the Current Test Run menu in the Test Steps panel of the Execute
Tests section of the Test Case. When you click the Start Test Case button, if the Test Case has not been
planned in the selected Test Run, a confirmation dialog box appears informing you that the Test Case is
not planned in the Test Run. You are then asked to confirm that you want to execute the Test Case. You
clickExecute to proceed, or Cancel to cancel the execution.
Multiple Test Runs can be run simultaneously, even when they contain the same Test Cases.
Procedure
Projects may be configured to require testers to electronically sign executed Test Cases. If your project is so
configured, then when you mark the Test Case Verdict, a dialog displays requesting you to sign by entering
your user name and password. See Signatures for Test Case Execution.
By default, any unresolved Defect (or equivalent type Work Item) from any Iteration in the current Test
Run, or from any iterations in the previous Test Run (or the previous Test Run in the same group) is reused
for failures of the same Test Case if the Test Case failed in the most recent execution.
In Test Runs that use Test Cases from different projects, this works differently. A Defect item can be reused
only if it is linked to a test record in a Test Run in the same project as the current Test Run. This also applies
to Failed in previous and Failed in group reuse strategies. For example, suppose "Project A" uses defect
reuse strategy always. You execute a Test Case in a Test Run in this project which fails. The previous Test
Run in which the same Test Case was executed is in "Project B". This previous execution failed, creating a
Defect item that is not resolved yet. That defect, in "Project B", is not reused. Rather, a new one is created in
the project specified in the testing configuration in "Project A".
Procedure
1. Select a finished Test Run from the list of available Test Runs.
2. Click Passed, Failed or Executed in the Test Run Status section.
The Test Run's results appear in a list.
3. Click Show in table.
4. The Test Run's details appear.
Tip
If you know the target Test Run you can also enter it directly as a search parameter.
(The results are read-only. Test Cases can not be retested in a finished Test Run.)
When manually executing a Test Run, you can optionally add a file attachment to each individual Test
Step, or to a Test Record. For example, you might attach a screenshot image illustrating the result of a
failed Test Step. This topic describes several important points you need to know about these attachments.
You can export Test Runs to Microsoft Excel, manually execute test cases and associated Test Steps offline/
externally, and then import the results into Polarion via the Excel file previously exported. This approach
automatically creates test records in the system for all exported Test Case items. The approach can be
useful if you use external testers who do not have access to your Polarion system.
You can also use the same method to manually record the results of externally-run automated tests in an
exported Excel file, importing the results back to Polarion. However, if you use automated testing tools,
you may prefer to set up automated import of automated test results into Polarion. See Integrating with
External Testing Tools for more information.
On export, all unexecuted Test Cases selected for the test run are exported. The export includes any Test
Cases from other projects selected via the Project Span field of the Test Run or the underlying Test Run
Template. On import, Test Records are created for all the previously exported Test Cases. If Test Case
selection spans across different projects, the following limitations currently apply:
Begin the external testing process by exporting the Test Run to be executed externally to a Microsoft Excel
workbook file.
Procedure
1. Open the project containing the Test Run you want to execute externally.
2. In Navigation, select Test Runs. On the Test Runs page, select the Test Run you want to manually
execute (or for which you want to manually record results of external automated tests).
All relevant Test Cases should already be selected. If not, select them as described in Select
(Planning) Test Cases.
3. In the Test Run detail, click Export Tests to Excel and save the exported Excel file to your local file
system. The default file name is the name of the Test Run. You can optionally save with a different
name without affecting subsequent re-import of test results.
You can send the exported file to someone else who will actually perform the manual tests (or manually
record the results of externally-run automated tests). The tester can execute each of the Test Cases of the
Test Run in whatever way that is normally done, performing the steps by hand or running some tool and
logging the result of each Test Case in the Excel file. When manually executing tests, as each Test Case is
executed, the tester logs the result of each test step in the Step Verdict column of the Excel sheet for each
Test Case and records the overall result of each Test Case in the Test Verdict column. Testers can optionally
add or change the content of the Comment column. These columns, and those for logging results, are the
only ones external users can edit. All others are protected.
After all tests for the Test Run have been performed and their results entered and saved in the Excel file,
the tester returns the file to the Polarion user who exported the Test Run (or any user with the same
permissions), who then imports the results file back to Polarion so that the results can be recorded and
tracked.
Tip
If your project is configured to require an electronic signature for Test Case execution, you are prompted
to provide your e-signature. A signature must be provided for the process to finish. Nothing is imported if
you cancel the import without providing the requested signature.
When the process is finished, the dialog informs you of the result: successful import or import failure.
Assuming success, it displays statistics about the number of Test Cases executed and the number that
passed. In every case, there is a link to the import log file which displays the process log in a new browser
instance.
A successful import creates a new Test Run record. You can access records via the Actions menu
button in the header of the Test Run detail pane on the Test Runs page.
Note
Adding new Test Cases in an Excel workbook exported for external test case execution is not allowed in
the exported file. If you want to use Excel to define new Test Cases, use the Import from Excel feature to
define new test cases in Excel and import them into a Polarion project.
Polarion provides a default template for exporting Test Cases to Microsoft Excel for external testing. It
should be sufficient for most situations. However, administrators can download the default template file
which can then be used as the basis for one or more custom export templates. One customization that
may be desirable when exporting Test Runs that select Test Cases from multiple projects is to show the
source Project of Test Cases in a dedicated column.
An administrator can upload customized template files, which users can subsequently select as templates
for exporting Test Runs to Excel. For information, see Configure Test Export Templates.
Polarion can support your formal testing review and sign-off process for Test Runs, using secure electronic
signatures compliant with U.S. 21 CFR Part 11. A Polarion administrator can map your review and sign-off
process to the Test Run Workflow configuration. Each step in the process can optionally be set up to
require an electronic signature before a Test Run can move to the next step in the workflow.
To be able to sign a Test Run you must have permission to READ and permission to MODIFY Test Runs.
Signing a Test Run takes place when you invoke any status change that is configured in the project
workflow as requiring a signature. For example, setting the status to Passed might be so configured.
Procedure
1. Open Test Runs topic (Navigation Test Runs) and select the desired Test Run.
2. On the toolbar of the detail pane, click Properties.
3. Go to the Status field and select the desired transition action. The actions in the list can vary from
project to project depending on the project's workflow configuration. For example, one project might
have an action "Perform action Mark as Passed" while another project might have an action "Mark
Executed Without Failures".
4. On the pane toolbar, click Save. If the selected action is configured to require a signature, the Enter
User Name and Password dialog box appears with the Username field focused.
5. Enter your Polarion user name and press Enter, or click Next. The Password field appears.
6. Enter your password and press Enter or click Sign.
• You can show Test Run signature information in Pages using the Test Run Signatures widget.
• In the rare case where logging a signature conflicts with concurrent changes to the Test Run made
by another user, Polarion displays a dialog box with information and options for proceeding. You can
review the other user's changes before saving yours.
The Properties page of a Test Run contains a section for comments. When signing a Test Run, or making
other changes, you can add a comment. Test Run comments work in the same way as comments in Work
Items. Other users can reply to a comment, there can be multiple comment threads, and comments can be
marked as Resolved.
On the Test Runs page, users can search for a Test Run by comments by typing a query containing fields
comments.title, comments.text, comments.author.id, or comments.resolved, or via full-text search.
• Add new comments to a Test Run (requires permission to comment Test Runs).
• Reply to existing comments (requires permission to comment Test Runs).
• Resolve comments or comment threads (requires permission to resolve comments in Test Runs).
Note that permission to read Test Runs is also required for all of the above.
Procedure
3. In the Test Run detail, click Properties, and then click the (Scroll to Comments) icon.
At some point you may decide you don't need to preserve all the executed Test Runs. This is especially
likely if you have integrated automated test execution with Polarion's building feature, creating new Test
Runs with every build. You can delete one or more Test Runs from the Test Runs topic. You must have
permissions for this action, otherwise you will see a message and the delete operation will be canceled.
Procedure
3. If you are deleting a single Test Run, go to the lower pane, click Actions, and choose Delete.
If you selected multiple Test Runs to delete, a button labeled Delete [N] selected Test Runs appears
in the lower pane of the Test Runs page (where [N] is the number of Test Runs selected in the upper
pane). Click the button to delete all the selected Test Runs.
If you have many Test Runs as a result of automated testing, it may not be practical to delete old Test Runs
manually. In this case, Polarion provides an automated job that deletes Test Runs you don't need to keep.
For information, see Configure Cleanup of Old Test Runs.
Every Test Run has a Keep in History field, accessible in the Test Run's properties. When checked, the Test
Run is preserved in Project Baselines. Before starting automated cleanup of Test Runs, you should mark
those Test Runs to preserve in history for future reference. For example, you might keep all Test Runs for
verification tests that were executed at some project milestone. Project managers should be aware of when
the automated cleanup job is scheduled to run, and should mark any new Test Runs to preserve in history
before the next scheduled Test Run cleanup.
Marking is simple when there are only a few Test Runs and only one or two to be marked. You can browse
your project's Test Runs and mark each Test Run individually in its Properties. If there are many Test Runs
in the system, and/or many to be flagged for preservation in history, then you need to use bulk marking of
Test Runs with the Keep in History flag.
Procedure
Polarion maintains a record of all instances of the execution of a Test Case during any Test Run which
includes the Test Case. You can review the most recent records for any Test Case in the Test Records
section of the Work Item Editor when a Test Case is selected. You can view the past test execution records
up to the limit set in the system configuration, selecting the period in the drop-down list provided. The Test
Records section shows the results of the reported test executions, including Iterations of Test Steps and
provides links to each of the Test Runs. The current content of the Test Records section is included if the
Test Case is sent to Print. If the record table contains additional details, its content is expandable.
Each Test Record is linked to the revision of the test case that was executed during the testing session that
resulted in the creation of the record.
Polarion has an embedded SQL database layer that can facilitate Work Item queries in traceability reports
and with other complex querying needs. One common need is some query function that enables you to
search for Work Items such as test cases, or defects, according to Test Records — to find items matching
such descriptions as "failed test cases executed by me in last week", or "defects triggered by test cases", to
cite just two of many possible examples.
The TEST_RECORDS keyword, with parameters, can be used in the Work Items Table view for such kinds
of queries. It bypasses the usual Lucene query engine and queries the index of the SQL database layer.
For information on syntax and parameters, and usage examples, see the Reference topic Test Records
query extender.
Procedure
1. With the relevant project open, click Test Runs in Navigation, and in the table of Test Runs, select
a Test Run by clicking on its row. The detail of the Test Run loads in the lower part of the page.
2. On the toolbar of the Test Run detail, click the History icon. A table of the historical revisions to
the test run replaces the Test Run detail information.
You can access the detail of any revision by clicking on the revision number. To exit the history, click the
History icon again.
In manual testing, it is common for the testing steps of a test case to be executed multiple times with
variations in the test procedure. For example, the same set of steps might be run on desktop and
mobile operating systems, and/or with different browsers on the different operating platforms, or an
electromechanical component might be tested with different input voltages. Polarion's Test Parameters (or
"Parameterized Testing") feature can help make the test specification process efficient and flexible.
The discussion of this feature assumes you are already familiar with the information in Creating and
Managing Test Runs.
Rather than create separate test cases, or different sets of steps, it is possible to capture the variables in the
testing process as Test Parameters, which can be applied by testers during different executions of the same
Test Case. Test Parameters are placeholders for actual values. They enable test case authors to write test
cases and steps in an abstract way, thereby enabling testers to execute them with specific variations.
For example, suppose you are testing a logon operation for a web application. Your steps might be as
follows:
Suppose you want to run this test using different browsers/versions and/or different user accounts. Rather
than write separate test cases with similar steps, Test Parameters named Browser, Username and
Password can be created and inserted into test steps when writing up a test case.
Tip
You can query test records based on test parameters.
Authors/planners of Test Runs can supply values for the Test Parameters in the Test Cases planned into
individual manual Test Runs. Examples of parameter values in the above simple test might be Firefox
40, sampleuser, and samplepass in one Test Run, and Chrome, sampleuser, and samplepass
in another Test Run. During execution of Test Runs, testers see these values and perform the steps
accordingly. Test Records are automatically created showing the step results with Test Parameter values
applied.
If a single Test Case needs to be executed multiple times with different variables applied, multiple
Iterations can be defined for the Test Steps with different parameter values specified and applied for each
execution of the steps.
• All changes to Test Parameters, such as creating new, renaming, and changing values, are written to the
History of the artifact in which the change takes place like Test Run Template, Test Run, or Test Case
item.
• Changes to Test Parameters are shown in the Activity stream. The entry shows the user who made the
change, what artifact was changed, and what parameters changed.
• By default, changes to Test Parameters are included in the information sent via notification events for
Test runs
Also, Test Parameters can optionally be shown as a column in the Test Runs table via the Customize Table
action on the toolbar of the Test Runs table. In the dialog box, you add Test Parameters to the Columns
Shown list.
This topic is mainly for testing managers or team leaders who plan testing activities and develop standards
or best practices for a team or project by means of Test Run Templates. You can configure Test Run
Templates with Test Parameters (and, optionally, default parameter values), so that when a Test Run is
instantiated from a template, the Test Run contains the parameters (and values, if configured) defined in
the template. When the instantiated Test Run is executed, the respective values from the Test Run are
prefilled in Test Parameters in any Test Cases that have the same parameter in the Test Steps.
In the above example, it would make sense to define the Browser parameter in the Test Run Template
because it is the testing environment and therefore global for all the Test Cases in all Test Runs based
on the template. Then, in each Test Run, a value for Browser can be specified ("Firefox" or "Chrome" for
example), which becomes the default parameter value in the Test Cases selected for the Test Run.
Consider a simple example that illustrates how this feature works, continuing with the idea of testing the
logon function of a web application. The test environment is always a web browser. The testing steps
direct the tester to open the browser, access the application URL, and enter the logon credentials user
name and password. The test checks both valid and invalid credentials. Let us assume that a parameter
Browser is defined in a Test Run template named "Web-app Logon Test". When a Test Run is created from
that template, it contains the Browser parameter, but no value for it. This parameter can be saved to the
Test Parameters Library, making it available to Test Case authors for insertion into Test Steps.
Now suppose you, the test planner, want a Test Run instantiated from this template to execute Test Cases
using Firefox version 40. You supply Firefox 40 as the value for the Browser parameter in the Test
Run you create for this test. Let's assume the existence of a Test Case in which the author created Test
Steps containing Test Parameters Browser, Username, and Password, and that you have selected it for
execution in your Test Run.
When you open the Test Case via Actions Select Test Cases in the Test Run, you see the value
"Firefox 40" in place of the Browser parameter in the Test Steps. This value is from your Test Run. You
now need to supply values for other parameters in the Test Steps, so testers executing the Test Run know
how to actually execute the Test Case. You can do this in the Iteration 1 panel of the Test Run Planning
sidebar.
After specifying all parameter values, you save the Test Run via the button in the sidebar. (You can
optionally add Iterations and provide different values for the parameter.) At this point, the Test Run is ready
to be executed by Testers.
When a tester executes the Test Run via Execute Test, the Test Run execution view opens. The table lists
the Test Cases selected in the Test Run. Test Parameters in the Test Steps are replaced by the actual values
supplied by you, the Test Run author/planner. The tester proceeds to execute the steps according to the
information. The parameter values in the steps are written to the test record.
Note
A tester with the requisite permissions can modify parameter values during execution of the Test Run.
Any changed values are written to the test record, so the actual values used to execute the test are
always traceable.
Define Iterations
Test Steps of Test Cases often need to be executed multiple times with variations. In the example we have
been using, this might mean running a different browser or browser version, or a logging on to a different
user account with different access permissions. When defining a Test Run, the Test Run author/planner can
add another Iteration in the Test Run Planning sidebar of any selected Test Case and supply the different
values for the Test Parameters in each Iteration. You can add as many Iterations to be executed to cover all
possible scenario variations.
After Iterations are defined and the Test Run saved, a tester can execute the Test Run, performing the
Test Steps multiple times using different values each time as specified in each Iteration. Because Iterations
are individual rows in the table, they execute completely independently. (Each can be started, paused,
resumed, or completed separately.) The results of each Iteration are stored as one test record. Iterations
appear in the order and position defined in the test run. For example, if another Test Case resides between
two Iterations in a Test Run and Auto Start is configured, this Test Case starts before the subsequent
Iterations of the initial Test Case.
Warning
Iterations are only supported in Test Runs where Select Test Cases is set to Manually, (this includes
Test Run Templates), or if they are selected via the Query on Create or LiveDoc on Create
options.
Generally, you want to perform the following operations in the order described, though there may be
some concurrency, and some steps are optional, as noted.
When composing Test Cases, test specification authors who have the requisite permissions can optionally
save Test Parameters they create to the project's Test Parameters Library. For example, if a common test
environment is a web browser, it would make sense to add a parameter named Browser to the library. The
parameters saved to the library appear as items in the Insert Test Parameter select list in the Test Steps
table of Work Items of Test Case type, when a Test Case author is editing the table and defining Test Steps.
It is also shown in the Parameter Name column of the Manage Test Parameters dialog box, accessible in
Test Runs and Test Run Templates.
An administrator can access this library in the project Administration and perform several operations
including defining new Test Parameters and modifying or deleting existing parameters. In the
Administration configuration, you can only specify Test Parameter name and type. Parameter values are
specified by users who create Test Runs.
Tip
In first releases of the parameterized testing feature, only the String type is supported.
Procedure
1. Open the project while logged on with administrator permissions and enter Administration.
2. Expand the Testing topic and select Test Parameters Library.
You can configure Test Run Templates with Test Parameters so that when a Test Run is instantiated from a
template, it contains the parameters defined there. In essence, you define the default Test Parameters for
all Test Runs based on the Template. You can add Test Run Parameters in both new and existing Test Run
Templates. You can optionally provide default values for the parameters you define in a Test Run Template.
The values appear in Test Runs instantiated from the template.
In a Test Run instantiated from a template, users with the necessary permissions can:
To work with Test Run Parameters in Test Run Templates, you must have permission to MODIFY Test Runs,
and permission to DEFINE TEST PARAMETERS in Test Runs.
Procedure
6. In the Manage Test Parameters dialog box, click the icon to add a new Test Parameter. Select from
the list of parameters currently in the Test Parameters Library or enter the parameter name and type
(if multiple types are available). Click OK when finished adding Test Parameters.
When finished with all templates, click Manage Templates to switch it off and return to the Test Runs
management page.
This section applies to anyone who plans tests, creating and configuring Test Runs. When you create a
new Test Run, you can define Test Parameters and their respective values. In the Test Cases selected for
the Test Run, if the Test Steps contain a parameter of the same name as one defined in the Test Run,
the Test Run supplies the value when the Test Cases are executed by testers. The Test Run author/planner
must supply values for Test Parameters in Test Cases that do not have an equivalent parameter defined
in the Test Run. Alternatively, testers can be given the necessary permission to modify parameters when
executing the Test Cases of a Test Run.
For example, Test Case TC-1 might contain a step Open Browser where "Browser" is a Test Parameter. A
Test Run might then define a parameter Browser with a value Firefox 40. When TC-1 is selected for the
Test Run, the tester sees the step as Open Firefox 40 - the value "Firefox" is supplied by the Test Run
during execution.
To specify Test Parameters, you should be familiar with the Test Cases or the needs of Test Case authors
who are writing the Test Cases and Test Steps that will be tested when executing the Test Run. For
example, if some Test Cases need to be executed in different web browsers, you can understand that it's
useful for the Test Run to have a parameter named Browser.
Procedure
Your next task is to open the Test Cases selected for your Test Run and provide values for any Test
Parameters they contain for which there is no equivalent Test Parameter in the Test Run. For example, if
some Test Case has a parameter User that is not also configured in the Test Run, you need to provide a
value for it at the Test Case level.
1. Select the Test Run on the Test Runs page and make sure Test Cases are already selected. (Selection
mode must be Manual, By query on create or From LiveDoc on create.)
2. With the Test Run selected in the table, click Actions and choose Select Test Cases. A table of
Work Items appears listing the selected Test Cases.
The Test Run Planning sidebar also opens in the view displaying information about the number of
waiting executions and other Test Run statistics.
3. For each of the Test Cases, in the sidebar panel labeled Iteration 1, enter values for all empty
parameter fields.
4. Click Save Test Run to update the Test Run.
By default, each Test Case has one Iteration. If a Test Case needs to be executed multiple times with
different parameter values, click Add Iteration. A sequentially numbered Iteration panel is added to
the sidebar, with parameter values prefilled from the previous Iteration. Modify the parameter values as
needed so that testers process the steps correctly. Add additional Iterations until all necessary variations of
the Test Case are covered. Be sure to save changes using Save Test Run.
When all Test Cases of the Test Run have values, click the Test Run ID in the Test Run Planning sidebar to
return to the Test Run. (Which is now ready for testers to execute unless you wish to make other changes.)
This section applies mainly to authors of Test Cases. The Test Parameters feature (sometimes called
"parameterized testing") enables you to write abstract test procedures, inserting Test Parameters in place
of some concrete specifications. When selected in a Test Run, a test planner, manager, or a tester with the
requisite permissions can supply concrete values for the parameters in the Test Steps. These values become
part of the automatically created test records.
For example, in a Test Case that describes a test that must be run on different mobile operating systems,
instead of writing "Android", "iOS", or "Windows Mobile" in a Test Step, you could insert a parameter named
OS. When planning the Test Case to a Test Run, a test manager can then supply a concrete value in place of
OS, depending on which platform is being tested.
The Test Parameters can be defined in any or all of several different places:
When writing a Test Step in a Document or in the Work Items Table, you can insert any existing Test
Parameter (already defined in the Test Case, or the Test Parameters Library) into your text. Or, you can
define a new Test Parameter and insert that, optionally adding it to the library. You must have access
permissions granted for the relevant folder in the Polarion repository in order to add Parameters to
Library. Writing to this location is not granted by default for nonadministrator users. (See define the Test
Parameters Library.) You must also have the Polarion user permission "ADD TO PARAMETERS LIBRARY".
The list includes parameters already defined the Test Case and/or Test Parameter library.
Procedure
1. Click the header of the Test Steps table in the Test Case. The table transitions to edit mode.
2. Place the insertion cursor at the point in the table where you want to insert a Test Parameter. This is
typically in the Step Description column.
3. In the drop-down options list beneath the last row of the table, click Insert Test Parameter.
4. Select one of the parameters in the drop-down list; you can filter the list by typing. Alternatively,
create a new parameter by clicking the Add New item and entering properties for a new parameter in
the Add New Parameter dialog box.
This section applies mainly to a testing manager or team leader creating and setting up Test Runs. During
planning of a Test Run, the author/planner must supply values for any Test Parameters defined only on the
Test Case level (that is with no equivalent parameter in the Test Run). For example, if the Test Case author
defined a parameter OS, the Test Run author/planner must replace that with some concrete value, such as
iOS or Android, if there is no parameter in the Test Run named OS.
When the Select Test Cases field of the Test Run is set to Manually, By Query on Create, or From LiveDoc
on Create, you can click Waiting or Execute Test in the Test Run and click Open Test Cases in Table
to open the selected Test Cases in the Work Items table in a new tab. Then you can begin supplying
parameter values per the steps outlined below. When the Test Case selection mode is set to By Query on
Execute or From LiveDoc on Execute, Test Parameter values cannot be specified at the Test Cases level.
Values must be set in the Test Run, from which the Test Cases selected on execute will inherit the values.
Also, multiple iterations per Test Case are not supported for the "on Execute" selection modes.
Procedure
1. Select the Test Run in the Test Runs topic in your project.
2. Click Waiting or Execute Test in the Test Run Status section of the Test Run.
3. Click Open Test Cases in Table.
A new browser tab opens and displays the Work Items table, with the Test Cases of the Test Run listed
and the Test Run Planning sidebar open.
4. Select the first Test Case in the table, and in the Parameters section of the sidebar, specify values for
any Test Parameters that do not yet have one.
Any filled-in values are coming from the equivalent parameter in the Test Run.
Repeat these steps for all other Test Cases of the Test Run listed in the table until you have provided Test
Parameter values for all of them.
Procedure
1. Be sure you have specified all missing values in Iteration 1 (always present and cannot be removed).
2. Click Add Iteration in the sidebar to create another Iteration.
3. Fill in values for all Test Parameters. Repeat this step to create as many Iterations as you need to run
the Test Steps with all possible parameter value variations.
4. Click Save Test Run in the sidebar to update the Test Steps.
5. Go to the previous tab and select and review the Test Case in the Test Run execution view. Check that
all parameters are replaced with actual values in all Iterations in the Test Run execution view.
Any parameters missing a value are highlighted in light red.
You should now see all actual values for all Test Parameters in the Test Steps, highlighted in light blue.
Warning
Testers cannot execute a Test Case until all Test Parameters in all Iterations have a value. If execution
cannot proceed for this reason, the Start button in the Test Run execution view is disabled.
This section is mainly for testers who execute Test Runs that include Test Cases with Test Parameters in the
Test Steps (that is, parameterized Test Cases).
Before executing Test Steps in a Test Case, a value for all Test Parameters in the Test Steps table must be
specified, except those whose value is specified in the Test Run you are executing. Normally this should
already be done by the creator of the Test Run. However, testers can be granted the requisite permission
to modify Test Runs and define Test Parameters. In this case, it is possible to provide values for Test
Parameters in the Test Run Planning Sidebar during execution of a Test Run. You should follow the
procedures described in Provide Parameter Values in Test Cases before you begin executing the Test
Steps, except in Step 2 you should use the Execute Tests button rather than the Waiting button. Click
Open Test Cases in Table to open the list of Test Cases and the Test Run Planning sidebar in another
view. Test Run Planning sidebar opens only if you are using a license that allows Test Run modifications
(such as ALM or QA).
Note
It is possible to override any default parameter values provided by the Test Run if you have the requisite
MODIFY permission for Test Runs.
Once all Test Parameter have been supplied with values, you are ready to begin executing the Test Case.
Launch the Test Run in the normal way using Execute Test. The button panel indicates how many total
executions of the Test Cases are waiting. In the first Test Case, click Start to begin executing the test.
The main difference between executing regular Test Cases and parameterized Test Cases is when there are
multiple Iterations. When there are multiple Iterations, each is represented by a new row in the Test Case
table while executing the Test Run. Test Runs process Test Cases in the order that they are listed in the Test
Run execution view.
Also, if you have permission to MODIFY Test Runs, it is possible to add more iterations while executing
other Iterations.
(To do so, click Open Test Cases in Table to open the Test Run Planning view.)
Warning
If you do this, be sure to click the (Refresh) icon in the sidebar after adding an Iteration and modifying
the default values, in order to update the test record. Also, click the (Refresh) icon in the execution
view to refresh the view of Test Steps. Remember that you can pause the Test Case and resume testing
later. On pause, the current state of the current Iteration is logged in the test record.
Polarion supports off-line execution of parameterized Test Runs via export/import to Microsoft Excel. For
detailed information on this feature, see Excel round-trip. There is essentially no difference when Test
Cases are parameterized, except that:
• The exported Excel workbook contains sections for all Iterations of each Test Case. Testers can log results
of each step in each Iteration.
• Test Parameter values are rendered in bold font in a light blue color.
• By default, Iteration names are appended to the Test Case title in the Title column, for example, "Test
Valid Login - Iteration 1".
• If any Test Parameters in any Test Case in the Test Run have no value assigned, Excel round-trip export
fails with a message citing which Test Cases are missing parameters.
• By default, all selected Test Cases of the Test Run that have waiting Iterations and/or no results are
exported to Excel. If incompletely executed,Test Cases are included in the exported Test Run. All
Iterations are exported, whether or not they have been executed.
• Excel round-trip files containing only partial results may be re-imported to Polarion, in which case only
new Test Records are imported.
• A tester can retest Test Cases and iterations by changing the result in the exported Excel workbook.
When a workbook with retested Test Cases is imported back into Polarion, check the option Retest
previously executed Test Cases in the Import Results from Excel dialog.
Alternatively, the Test Run can be re-exported and the Test Cases re-executed. On re-import, the Retest
previously executed Test Cases should be checked.
• The column to which the Iteration name is appended is configurable in the export template, so you may
see it appended to some other column than Title in the exported workbook. For more information, see
Excel Round-trip Templates and Specify Column for Test Step Iteration Numbers.
Polarion provides the option of using external testing tools and using Polarion as the central repository for
tracking and reporting the results of testing. For example, you might use Eclipse TPTP for automated load
and performance tests, and Selenium for automated user interface testing, importing results of every test
execution to Polarion where the results are visible to stakeholders and history of testing is maintained. You
can use Polarion in this way with any external tool that can export test results to the xUnit XML format.
To integrate xUnit test results from an external testing tool with Polarion, you configure each of your
external tools to write an xUnit file to a folder accessible to Polarion, and configure Polarion to periodically
check each folder for the presences of a test results file. A scheduled job named xUnitFileImport is
provided in Polarion which checks a specified folder. If any file is found there, the test results it contains
are imported to an automatically-created Test Run. The test results file is deleted from the disk so that the
folder is empty, and will be empty until the external testing tool executes another round of testing and
writes another results file to the folder.
For information on scheduling and configuring jobs, see Configure the Scheduler. The job may also be
invoked explicitly by a user in the Monitor.
The following listing shows the job configuration syntax. The cron expression is just an example of one you
might use to specify when the job should run. For more information on cron expressions, see Scheduler
cron information and examples.
<path> is the folder where Polarion should check for a test results file.
<project> is the name of the project into which the test results data are to be imported.
Note
The Group ID field of the Test Run is filled with the name of the imported test results file (minus
extension).
xUnitFileImportUser references keys in the User Account Vault file (more info follows). If no user is
specified in these keys or if the <userAccountVaultKey> element is empty, then the job can only be
run by a user invoking it from the Monitor, and the job runs on that user's account. It will fail if allowed to
run automatically according to the cronExpression schedule because such jobs run on the system user
account which does not have write access.
In order to run the job automatically, it is necessary to configure a user in the User Account Vault on who's
behalf the job will run. The User Account Vault is a properties file stored in the file system of the Polarion
installation at data/workspace/user-account-vault/accounts.properties. The file contains
the following two keys, which are referenced by xUnitFileImportUser when that value is specified in
the <userAccountVaultKey> element of the job configuration (see example job listing above):
xUnitFileImportUser.user=[USER_ID]
xUnitFileImportUser.password=[USER_PASSWORD]
Where [USER_ID] and [USER_PASSWORD] are the ID and password, respectively, of the user on whose
behalf the job should run. The specified user must have write permissions for the project specified in the
<project> element.
See also:
Polarion provides visibility and information about the status of testing and testing results. The two main
vehicles are:
Dashboards and reports access the most current project and testing data in the repository at the time they
are updated. Dashboards are updated according to the configuration of the scheduled job that updates
dashboards and can be explicitly updated to show up-to-the-minute information. Report pages are updated
when viewed and can be exported to PDF any time. When you use a product license that supports it,
the Quality topic appears in the Topics section of the Navigation Quality Dashboards, Audits, and
Metrics panel. This topic provides a number of dashboards summarizing key quality-related information
and statistics.
You can create custom report Pages especially for quality assurance and testing reports. The Testing space,
available in projects based on one of Polarion's project templates that provide it, is a good place to create
your report Pages. QA and testing project templates provide some standard reports such as Test Case
Traceability and Testing Dashboard. You can modify any of the default report pages or copy and paste their
content to a new page, which you modify to suit your needs.
Polarion licenses with QA and testing support provide a number of macros designed to support testing
activities and reporting. For example, the {import-automated-test-results} macro enables page
users to launch import of test results.
You can find a complete reference to these macros, including syntax and usage examples, in the Test
Management section of the Wiki Syntax Help, which is accessible when you are editing any wiki page. You
can also access it at the following URL on your Polarion server:
http://yourpolarionserver.yourdomain.com/polarion/#/wiki/Doc/
SyntaxHelp#HTestManagement.
Note
Beginning with version 2012 several test management macros were deprecated in favor of new features
and removed from the Wiki Syntax Help. However, these macros can still be used. See Deprecated
Macros: Test Management.
Test results and records are included in Project Baselines. So, for example, if a Project Baseline is created
at the time of a release, you could go into it to see what test cases were executed in time of release. In
baseline view, the Test Runs topic shows data as they were at the time the Project Baseline was created.
Manage Variants
Using Polarion, you can centrally manage specifications and other assets for a product line, generating
product-specific variant specifications.
Many companies today have highly diverse product lines and offer different product models or
configurations with different feature sets. A critical need in developing the product is the ability to
effectively manage these commonalities and variations in the various specifications.
Polarion VARIANTS, an add-on to an existing Polarion installation with a dedicated back-end server
component by Pure Systems and project templates, helps you manage variants.
• You can maintain the specifications for requirements, tests, and risk assessment in a single master
specification document for each artifact type that covers the entire product line.
• You can reuse different applicable subsets of these master specifications to create specifications, fully
covering each product in the product line.
License requirements
Your ability to access variant management functionality is license dependent. The following table outlines
various use cases and the licenses required.
Req/QA/ALM/
Reviewer/PR Req/QA/ALM /Polarion Polarion X w/o
Use Case O X + Variants Add-on Variants Add-on
Manage Feature Model - Yes Yes
Edit Restrictions and Constraints for - Edit Read-only
Master Specifications
Select Variant Features - Edit Read-only
Compare Variants (matrix) - Yes No
Generate Variant Specification - Yes No
Documents
View Variant report - Yes Yes
Note
All documents connected to Variant Management must have a Title heading.
Related Topics
Prerequisites
In order to use Polarion VARIANTS features with an existing Polarion installation, you must:
Variant management in Polarion is centered around Polarion LiveDoc Documents and Work Items
contained in Documents. We recommend that you become thoroughly familiar with these features
before you begin working with variant management.
Procedure
1. Go to https://support.sw.siemens.com/en-US/product/230235217/downloads
2. Select your Polarion version from the drop-down list in the Major Releases section.
Terminology
Master Specifications can be as granular as needed. For example, you can have
Master Specifications for Functional, Non-functional, and System Requirements.
Product Line Also called product family, it is the collection of all products a company
produces. The different products may have some common components that
must be in every product and some components that differ from product to
product.
Relation Links between Features that denote additional relationships depending on the
link type. For example:
• Feature Model validation: Checks for errors in the construction of the Feature
Model, such as inclusion of contradictory Features or failure to include a
Feature from a group from which at least one selection is required.
• Restriction validation: Checks the correctness of Restrictions set in Work Item
properties linking the item to one or more Features.
Variation Type A property of a Feature that describes the Feature's inclusion in product
specifications. A feature can have one of four Variation Types:
When not capitalized, denotes one specific product in a Product Line, for
example, "Model ABC is a variant of the WeatherStation product line".
Variant Description Assets, such as Requirements and Test Cases, that are mapped to Features that
Model (VDM) collectively make up a Variant
Variant Specification A specification Document generated from a Variant and comprised of
commonalities and variations from the Feature Model and Master Specification.
Process Overview
There are four basic activities in a variant management project with Polarion VARIANTS:
The Feature Model is a Document containing Work Items of the Feature type structured with parent-child
relationships to define features and subfeatures. The Feature Model contains all the features of every
product in the Product Line. It must be completed before any Master Specifications can be completed and
before any Variant Specifications can be generated. Only one Feature Model is allowed per project.
A Master Specification is a Document containing one or more Work Item types that define various
development artifacts such as Requirements, Test Cases, and Risks. A typical approach is to have different
Master Specification Documents for different artifact types, for example, Requirements and Test Cases.
With this approach, you can take advantage of Document Types. These can be defined by an administrator
in the project configuration, one for each type of artifact. You gain the possibility of defining different
workflows for different Document Types, which in turn provides the possibility of setting up different
approval processes with different groups of stakeholders signing off. A Master Specification contains all the
type-specific artifacts for the entire Product Line such as all the requirements or all the test cases.
A Variant is a special type of Work Item that represents a specific product in the Product Line. It is a
collection of Features linked to relevant artifacts in the Master Specification(s). It is subject to validation by
the Polarion VARIANTS back end to ensure integrity of the Variant Specification generated from it.
A Variant Specification is the complete specification for one type of artifact (for example, System
Requirements or Acceptance Tests) for one product in the Product Line. It contains only the requirements,
or test cases, or risks for the features of that specific product.
Note
Your ability to view or manage the above items may require the presence of a Polarion VARIANTS add-on
license. For more information, see License requirements.
Make sure that all documents connected to Variant Management have a Title heading.
Polarion VARIANTS comes with a project template and a demo project that have predefined support for
variant management. The Specification Project with Variant Management template is specifically for
creating variant management projects. The Weather Station demo project is based on this template and it
includes data and examples.
Creating a variant management project is no different from creating any other type of project. In the
New Project wizard page where you select the project template, simply select one of the templates that
supports variant management. The template description will indicate this.
The Feature Model contains the name and description of every possible feature of every product in a
product line. The Feature Model in Polarion VARIANTS is a LiveDoc Document configured to contain a
single Work Item type called Feature. The Feature items in the Document are structured with parent-child
relationships (shown by indent levels) that denote features and subfeatures.
If you create your project from a project template that supports variant management (recommended), the
Document, and the Feature Model space where it is stored, are created automatically. One Feature Model
Document is allowed per project. For projects created from other templates, some manual configuration is
required. For information, refer to Advanced Topics.
This section discusses several considerations around your Feature Model Document that you may want to
think about before beginning to work on it.
• Document Type: Consider whether to define a Document Type for the Feature Model Document.
Doing so enables you to have some configurations specific to that type, such as workflow and user
permissions.
• Document Workflow: Consider whether you need an approval process for your Feature Model
Document. If so, you should configure a Document Type just for the Feature Model, and configure
the Document workflow for that type to require user signatures before one or more status transitions,
such as a status like Draft or Approved.
• User Permissions: Consider whether you need to control access to your Feature Model differently from
other Documents and/or Work Items in the project. For example, you may want to restrict who can
approve a Feature Model Document or who can create or modify Feature type Work Items. If so, work
with your Polarion administrator to set up the controls you require.
• Work Item Type: If you know that Documents can be configured to contain more than one Work Item
type, you may want to configure your Feature Model Document with multiple types. This is fine for other
types of Documents, but your Feature Model should contain only one type: Feature. If your project is
created from a template with variant management support, the Feature Model document is created
automatically, and this type is predefined in the project configuration and set up in the Document
presentation configuration.
This section describes how to create a Feature Model in a variant management project. Some topics are
only applicable in projects not created from a project template with variant management support and are
noted as such.
It is good practice to keep your Feature Model in a dedicated Space. A Space named "Features" is
automatically set up in projects created from templates supporting variant management. You only need to
create a dedicated Features Space if your project is not created from one of these project templates.
You can create a new Space from the Index page of any existing space. On the page toolbar, click .
In the resulting dialog box, click the Create New Space link.
In projects created from Polarion project templates with variant management support, a Document named
"Feature Model" is automatically created in the Feature Model Space, and there is an icon in Navigation
that opens it for editing. In projects not created from a variant management project template, you should
create a new Document in your Feature Model Space:
2. Click and select LiveDoc Document in the Create New dialog box.
3. Follow the guidance in the next dialog box. Name the new Document "Feature Model", and select
Feature as the Work Item type.
The Feature type should already be defined in your project and appear in the list of Work Item
types. If it does not appear, cancel the operation and work with your administrator to create this type.
(The Feature type is predefined in projects created from Polarion's variant management project
templates.)
With the Feature Model Document in place, you are ready to begin constructing the feature model for
your product line.
To build your feature model, create a new Feature Work Item for every feature of every product in your
product line. In the Document Editor toolbar, click , or press the Enter/Return key when you insert
your cursor in an existing Work Item.
• Title: Identifies the feature for all stakeholders. It appears in feature selection lists and restrictions.
• Description: (Optional) Allows you to provide additional details.
Be careful not to specify requirements for a Feature in its description. Requirements should be defined
independently in a dedicated requirements specification Document that has a relevant Work Item type.
• Variation Type: Describes the Feature's inclusion in product specifications. In project templates
supporting variant management, this is an Enum custom field of Feature Work Items, configured
with the options as described in Terminology: Variation Type.
Tip
The Status field is one of the standard fields of all Work Items of all types, and the Work Item
Properties shows it by default in all Documents. However, the value of the Status field in Feature
Work Items has no impact on any aspect of variant management. You can safely ignore it when defining
Feature items.
You specify the Variation Type for a Feature in the Work Item Properties sidebar. If that sidebar is not
open, place your insertion cursor anywhere inside any Feature item in the Document, then drop down the
Show Sidebar menu on the Document Editor toolbar, and select Work Item Properties.
If the Variation Type field does not appear in the sidebar, take the following steps to show it:
1. On the Work Item Properties sidebar header, click , and choose Select fields.
2. In the Select Fields dialog box, make sure the Variation Type field appears in the list on the right. If it
doesn't, locate it in the list of fields on the left, select it, and click Add.
3. In the list on the right, select the Variation Type field, select Show in Sidebar only or Show in
Document and Sidebar and click Apply.
The sidebar configuration is saved per user and the setting persists if you navigate away from the
Document, and between logons.
Product-line feature modeling is a discipline in itself, and teaching it is beyond the scope of this help. The
Feature Model Document is a tool that enables variant managers to capture the product line features and
their relationship to one another. Then, specifications for variant products can be generated, which use a
subset of Feature Model features. The main relationship that needs captured is a parent-child relationship
to show that a feature is a subfeature of some other feature. For example, in a car, a parent feature might
be Headlamp, which has child features such as Halogen Headlamp or Mercury Headlamp.
You can create the parent-child structure of Feature items in a Feature Model Document by indenting the
items. You can decide when to create the structure. You may choose to do it as you create new Feature
items, or after all Feature items have been created, or a combination of these approaches. You should
undertake a comprehensive review of the Feature Model before beginning to create Variants.
Tip
An administrator can configure the Document workflow for your Feature Model Document to
support a review and sign-off process.
Development of the Feature Model can be a collaborative effort, with different people working to specify
different feature areas. For example, for a car product line, different people might specify the features for
the braking system, the drive train, and the driver electronics.
When designing your Feature Model, you can create links between different features with special link
roles that define dependency or exclusion between the linked features. Two link roles are predefined in
Polarion's variant management project templates, which can be used for this purpose:
• Requires: Denotes that, for example, Feature A requires Feature F. There is an opposite role, is required
by that can be applied if linking from the other direction: specifying that Feature F is required by Feature
A.
• Conflicts with: Denotes that one feature cannot coexist in the same specification as another. For
example, a feature such as Halogen Headlamp cannot coexist with a feature such as Mercury Headlamp.
You can link these features with this link role.
Note
Currently, these are the only link roles supported by the Polarion VARIANTS back-end server in its feature
validation process.
You can use these link roles in conjunction with Variation Type to provide more parameters for the
back-end process that validates features included in Variant Specifications. Variation Type provides a first
layer. For example, two features in a group might have the Variation Type "Alternative feature", which
allows only one to be included if the parent is included. These features conflict because of Variation Type,
so there is no need to link them with the conflicts with role. It would, however, make sense to link features
in different groups this way. For example, suppose two features like "Sensor North America" and "Sensor
Europe" should never be used in the same variant specification. Linking them as conflicting with each other
ensures that the validation process raises an error if the two are included in the same Variant.
For information on how to link items, see Linking Work Items. It outlines the approach recommended
when working with Documents.
In a variant management project, a Master Specification is a LiveDoc Document that contains all the
specifications for all the products in a product line. For example, a Master Specification might contain all
the requirements, test cases, and risks for a product line. For a large product line, you can have multiple
Master Specifications. For example:
• Master Requirements Specification: All the requirements for all the products in the product line.
• Master Test Specification: All the test cases for all the products in the product line.
The same goes for other artifact types such as risks and regulations. You can be even more specific with a
given artifact type. You might have Master Specifications for different kinds of requirements like functional,
nonfunctional, software, electrical, and mechanical. The main thing to remember is that each Master
Specification Document should contain all the artifacts of the given type for the entire product line.
You can take advantage of all the features of Polarion LiveDocs in your Master Specifications. For example,
you could configure a project to have a different Document type for each type of Master Specification,
and then configure appropriate workflows for each type, including an approval process which includes
different stakeholders for different Document types. You can also configure more specific user permissions
applicable to different Document types.
Polarion's project templates for variant management come preconfigured with a space named "Master
Specifications", which contains two Master Specification Documents: "System Requirements Specification"
and "Test Specification".
Each Master Specification Document should be configured to contain the desired Work Item type or types,
depending on the approach you decide upon. For example, the Document might be configured to contain
only Requirements, or both Requirements and Test Cases. An example of a Document configured to
contain two Work Item types follows.
You can create new Work Items in your Master Specification using the menu on the toolbar of the
Document Editor or by pressing your Enter/Return key when your cursor is inside an existing Work Item.
You can easily create a hierarchical structure of parent-child relationships between Work Items in your
Master Specification by indenting them to different levels. This is a common practice with requirements.
The following figure shows an example of a Master Requirements Specification using indentation to create
parent-child relationships.
Such structuring automatically creates links in the Work Items with a link role of has parent or is parent
of. These link roles can subsequently be queried, for example, for reports or dashboards.
Tip
It is recommended that you complete and review the structure of the Work Items in your Master
Specifications before creating Variants that draw items from them.
Define restrictions
Note
Defining and editing Restrictions requires that a Polarion VARIANTS Add-on license is present on your
Polarion server in addition to the Polarion license(s).
Restriction is an attribute of Work Items in a Master Specification. It is what ties any given item
to Features in the Feature Model so that variant specifications can be generated from the Master
Specification, which contain only those Work Items relevant to the specification for a specific product.
Restrictions are specified using the pvSCL language, the language of the Polarion VARIANTS Server Add-on.
Reference documentation for the language, developed by Pure Systems and widely used in their variant
management systems, is provided in the distribution of the extension
If no Restriction is specified for a Work Item in Master Specification, then it is included in all generated
Variant specifications. So you specify restrictions to indicate that, for example, some requirement is
included in Variant specifications only if the restriction expression evaluates to TRUE. Otherwise, if the
restriction is evaluated to FALSE, the item isn't included.
A special editor for specifying Restrictions in pvSCL is implemented in Polarion VARIANTS and appears in
the Restriction field of Work Items in Master Specification Documents included in variant management
project templates. The Restriction Editor can turn Full Screen mode on and off using the F11 key. It has an
auto-completion feature, invoked via the keyboard shortcut Ctrl + Space. You can access the Restriction
Editor in the Document Editor (see the following section), or you can open Work Items in the Work Item
Tracker and find it in the Custom Fields section of the page. The pvSCL editor is case insensitive.
If you want to use Restriction Editor in a Document, you need to open the Work Item Properties sidebar
when focused on a Work Item in a Master Specification Document. The editor is not shown by default,
so you need to perform the following steps to show it:
Procedure
1. Place the insertion cursor inside any Work Item in the Document, and open the Work Item
Properties sidebar.
2. On the Work Item Properties sidebar header, click (Pane Settings), and choose Select fields.
3. In the Select Fields dialog box, make sure the Restriction field appears in the list on the right. If it
doesn't, locate it in the list of fields on the left, select it, and click Add.
4. In the list on the right, select the Restriction field and select Show in Sidebar only, and then
click Set as Personal .
(Or Set as Default to have the settings apply to all users).
The sidebar configuration is saved per user, and the setting persists if you navigate away from the
Document and between logons.
Tip
The shortcut for auto-complete (Ctrl + Space by default) can be changed in the
[POLARION_HOME]\polarion\plugins\com.polarion.purevariants\pvscl.properties file by modifying the
editor.autocomplete property. (The first letter of Key names must be capitalized and multiple keys
separated by a hyphen. For example, Ctrl-B.)
Specify a Restriction
Warning
Your Feature Model should be complete before you begin specifying Restrictions in the Work Items in a
Master Specification.
The Restriction Editor has built-in completion assistance. The Ctrl + Space shortcut opens a list box
containing the Features in your project's Feature Model, and logical and Boolean operators. You can add
any item in the list to the Restriction expression in the editor field by double-clicking the item in the list
(see the previous figure).
The following steps assume you have a Master Specification Document open, and the Work Item Properties
sidebar configured to show the Restriction Editor, as described earlier in this section. You may find it useful
to have the Feature Model Document open in another browser tab or window.
Specify a Restriction:
Procedure
1. In the Document body, place the insertion cursor anywhere inside the Work Item for which you want
to specify Restriction.
2. In the Work Item Properties sidebar, click inside the Restriction field.
3. Press Control + Space, and in the list of Features, expressions, and operators, double-click the item
you want to add to the Restriction.
You need to fully specify all Restrictions in all Master Specifications before you can create Variants and
generate product-specific specifications.
Tip
You can search for the Requirement using a Restriction query followed by the Feature ID.
The pure::variants expression language pvSCL is a simple language to express constraints, restrictions,
and calculations. It provides logical and relational operators to build simple but also complex Boolean
expressions. Polarion VARIANTS uses a subset of the pvSCL language to link Features with Work Items and
to express relations between Features.
Boolean Values:
Expressions can resolve to a Boolean value, that is, TRUE or FALSE. An expression is said to fail if its
Boolean value is FALSE, and to succeed otherwise.
Logical Combinations:
Expressions can be logically combined. For this purpose the expressions are evaluated to their Boolean
values. It is an error if this conversion is not possible. The logical operator is then applied to the Boolean
values resulting in TRUE or FALSE. The simplest restriction is the name of a feature, but it is also possible
to build restrictions out of a combination of logical operators and multiple feature names.
Syntax:
Variant is a special Work Item type that collects specification items for the feature set of a single product in
a product line. It is possible to create Variant items in a Document configured to contain that type or in the
Work Items Table view. The latter approach is recommended.
Tip
Before undertaking operations described in this topic, you should complete the Feature Model and
Master Specification(s) for your product line.
Procedure
1. Open the project that contains the Variant Work Item type.
2. In Navigation, expand the Work Items topic, and select Variant. The Work Item Tracker opens
with only Variant type items displayed.
3. On the page toolbar, click and select Variant. A new Variant item opens in the Work Item
Editor.
After creating a new Variant item, the next step is to select the features of the product it represents.
Select Features
To select Features, you must be using a Polarion VARIANTS license, and you must have the necessary
permissions: MODIFY permission for the Work Item, and READ and MODIFY permissions for the Feature
Selection field.
The Work Item Editor (lower part of the page) contains a section named Feature Selection. If you have the
required license and permissions, the Select Features button appears in this section. Clicking this button
opens a new browser tab or window with a new instance of the Tracker, which displays a tree-table of all
the Feature items in the project Feature Model. The tree is automatically sorted by Variation Type, but
System Administrators can set it to sort by Outline Number by default instead with a simple addition to
the polarion.properties file. (See the following paragraph.) The tree is constructed on the parent-child
hierarchy of Feature items. The order for variation type is Mandatory, Optional, Alternative, and finally
OR.
In this instance of the table, you cannot change the sorting via the user interface. But you can enter a
query, and you can add/remove columns. It is, however, possible to have the table sorted by "Outline
Number" so that features are presented as they appear in most Feature Model Documents. A Polarion
administrator can add the following line to the system configuration file, polarion.properties:
com.polarion.variants.featureSelection.sortByOutlineNumber=true
The Polarion server must be restarted for the change to take effect.
Select items from the Work Item table. Link to Work Item.
Note
Some items can be already shown as selected. This is because the validation process on the back-end
server has implicitly selected them according to Variation Types and Restrictions.
The user interface indicates when features are added by the back end server.
The back end adds all required items up to root and Mandatory items below a selected item are added, if
they are not otherwise selected.
1. Open Variants in the Work Item Tracker (Navigation Work Items Variant).
2. Select the desired Variant item in the tree-table listing of Variant type Work Items.
3. In the Feature Selection section of the Work Item Editor, click Select Features.
A new browser tab or window opens with a new instance of the tracker, containing a tree-table of all
Feature items in the project Feature Model and a sidebar labeled with the name of the Variant item.
4. Explicitly include Features in the Variant by clicking the green check mark icon on the
Feature's row in the tree-table. Explicitly exclude Features by clicking the red icon. If you change
your mind, click again to deselect.
When you include some Features, other Features may be implicitly selected, denoted by a pale green
color in the check mark icon on the respective Feature rows. This happens because of the Variation
Type set on the different Features.
5. Save the Variant by clicking Save Variant in the sidebar. If there are many Feature to be selected,
it is advisable to save periodically during the selection process.
Validate Features
Note
This operation requires that a Variants Add-on license is present on your Polarion server in addition to
the Polarion license(s).
The Polarion VARIANTS Server Add-on provides back-end validation of the feature selection of the Variant
each time you save it (or open it). If there are any errors or warnings, then the sidebar displays a count,
and provides links to the details.
The Polarion VARIANTS back-end server checks the validity of a Variant and issues errors, warnings, and
information.
Clicking on the respective Errors or Warnings link in the sidebar displays a dialog box listing the problems.
The dialog box is modeless, so you can keep it open as you work on the feature selection to correct
problems. The dialog box is updated each time you save the Variant. Errors result from Variation Type and
link roles set on Feature items in the Feature model. For example, a Feature may have subfeatures with
Variation Type Or feature, which require that at least one must be selected, but none is selected. Selecting
one and saving resolves the error.
Warning
All errors must be resolved before any specification Documents can be generated from the Variant.
Like all Work Item types, the Variant type has a default workflow with defined statuses and actions that
transition to another status. And like all types, the workflow is customizable to conform to any process you
use. Among other possibilities, you can integrate a review and approval process for Variant items to ensure
accuracy and completeness before generating specification Documents from a Variant.
Note
This operation requires that a Variants Add-on license is present on your Polarion server in addition to
the Polarion license(s).
The final step in the process is to generate one or more specification Documents based on your Variant.
These Variant Specifications (sometimes referred to as "100% specifications") contain all the specifications
for one product in a product line. How many Variant Specification Documents you generate depends
on how many Master Specification Documents you include when you launch the Document generation
process. Generally, you would include all your Master Specifications. For example, if you have one
Master Specification for Requirements and another for Test Cases, you might want to include both
when you generate Documents from a Variant, resulting in a Requirements Specification and Test Case
Specification for a single product in your product line.
Include all Master Specifications. Last update of the selected master document.
Procedure
1. Open Variants in the Work Item Tracker (Navigation Work Items Variant).
The dialog box provides a link to the Monitor topic, where you can check the status of the job and
access the job log. The Monitor opens in a new browser tab or window. If the job should fail, the
log contains detailed information that can help you, your project administrator, or a technical support
engineer diagnose and resolve the problem.
Procedure
2. Click Generate Documents as you did when you generated them the first time.
3. Notice that the previously generated documents are automatically preselected in the Select Master
Documents dialog box, and all you have to do is click Next.
4. The Target Space and New Title fields are read-only and if you hover over the New Title field, a
tooltip appears showing the revision date of the Master Document that the previous version was
generated from and the Master document's Head revision date.
5. Click Generate.
6. A Generating Documents dialog box appears and provides a link to the Monitor to check the
progress of the generation. Click OK to close the dialog box.
Compare Variants
Polarion VARIANTS provides a quick easy way to compare your Variants. A special matrix view shows which
Features are used in which Variants.
Procedure
1. Open Variants in the Work Item Tracker (Navigation Work Items Variant).
2. Select any Variant item in the table of Work Items of the Variant type.
3. In the Feature Selection section of the Work Item Editor, click Compare Variants.
The Variants Matrix opens in a new browser tab or window. The structured Feature Model is rendered
as rows and Variant items as columns. You can filter the display using the special instance of the visual
Query Builder at the top of the page. For example, you might query for Features with "Obsolete" status and
Variants with "Active" status. This would reveal obsolete features in currently active Variants.
Note
Sorting the Matrix:
System Administrators can change this to Outline Number, the way it usually appears in Feature Model
documents, by adding the line below to the polarion.properties file.
com.polarion.variants.featureSelection.sortByOutlineNumber=true
There are two properties in the polarion.properties file that define the maximum number of cells in a
Traceability matrix or a Variants comparison matrix.
Variants are Work Items, and like all Work Items a change history is automatically recorded and
maintained. Access the history just as you would for any Work Item, for example, via the History button in
the Work Item Editor.
One particular feature of Variant history is that Feature selection is included. For any revision of a Variant
item, you can see if Features were added or removed, and if so, how many, when, and by whom.
In History and Project Baselines, the View Features button replaces the Select Features button. This is
also the case if feature selection is read-only, for example, the user does not have permissions needed to
select Variant features.
This topic contains information that may be useful when viewing a generated Variant Document.
When viewing a generated Variant Document, you may want to know the Work Item from which it was
generated, and access that item. You can find this by opening the Document Properties sidebar when
viewing the Variant Document. The Variant label displays the title of the source Work Item. The title is a
link that opens the Variant Work Item in a new browser tab.
When viewing a generated Variant Document, you may want to know the Master Specification Document
from which it was generated, and access that Document. You can find this by opening the Document
Properties sidebar when viewing the Variant Document. The Branched from label displays the title and
revision number of each Master Document used to generate the current Variant Document. The title is a
link that opens the indicated revision of the Master Document in a new browser tab or window.
You can query on variant.id or variant.title to search for all Documents that were generated
from a specific Variant item.
This section describes how to configure existing projects, created with a Polarion version prior to 2015,
or templates other than the Specification Project with Variant Management Template, or the Weather
Station demo project.
System requirements
Procedure
5. Now you have to setup a workflow for the newly created type. (Project Administration
Work Items Workflow)
6. Click Create to the right of the newly created Variant Work Item to get started.
See Configure the Work Item Workflow for more details on how to configure a Work Item workflow.
7. A recommended Status enumeration can be fairly simple, for example, something like Draft, In
Review, Defined and Rejected.
9. Define the following custom fields for the new Type. (Project Administration Work
Items Custom Fields)
10. Update the Work Item Form (Editor) layout. Project Administration Work Items
Form Configuration)
Add Variant Documents and Feature Selection as separate sections. Exclude the Feature Selection
field from the custom fields panel:
..
<field id="description"/>
<field id="featureSelection"/>
<field id="variantDocuments"/>
<!-- Description of panel is mandatory. -->
<panel description="Custom Fields">
<field id="@allCustomFields,-featureSelection"/>
</panel>
See Work Item Form (Editor) layout for more details if you are unsure about how to do this.
Tip
You can also create a new project using the Specification Project with Variant Management template
and reuse the configuration files by copying them to your existing projects:
• .polarion/tracker/fields/variant-custom-fields.xml
• .polarion/tracker/workflow/variant-workflow.xml
• .polarion/tracker/fields/variant-status-enum.xml
• .polarion/hats/_default/tracker/variant-form-layout.xml
Procedure
5. Now you have to setup a workflow for the newly created Feature type. (Project
Administration Work Items Workflow)
6. Click Create to the right of the newly created Feature Work Item to get started.
See Configure the Work Item Workflow for more details on how to configure a Work Item workflow.
7. A recommended Status enumeration can be something like: Active and Obsolete.
9. Define the following custom field for the new Feature Type. (Project Administration Work
Items Custom Fields)
(variationType as the ID, Variation Type as the Name, Enum as the Type, and select Variation Type
from the drop-down menu.)
See Configure Custom Fields for more details on setting up a Work Item custom field.
10. Configure additional link roles between the Feature type Work Items. (Project
Administration Work Items Enumerations workitem-link-role-enum.xml)
Tip
You can also create a new project using the Specification Project with Variant Management template
and reuse the configuration files by copying them to your existing projects:
• .polarion/tracker/fields/feature-custom-fields.xml
• .polarion/tracker/workflow/feature-workflow.xml
• .polarion/tracker/fields/feature-status-enum.xml
Specification Work Item types can be any Work Item type that will be part of your Product Line and will be
included in Master Specification Documents, for example, Requirement, Test Case, or SW Requirement.
Procedure
Add a custom field restriction to each Work Item type that will be used as a specification, such as
pvRestriction as the ID, Restriction as the Name, and pvSCL as the Type.
You can manage Variants across multiple projects, and select multiple Master Specification projects that
are separate from the Feature Model.
Note
Generated Variant Specification documents must reside in the same project as the Variant Work
Item.
There are two different methods for configuration cross-project variants. It depends on whether you want
to use the same configuration for all Work Items within a Project (the default), or you want to use Work
Item Custom Fields to use different configurations for all Variants.
The legacy method of creating a definitionProject custom field is still supported, but not
recommended.
Use the same configuration for all Work Items within a Project
Note
All configurations are optional:
Leaving them as --not selected-- will simply default to the current Project.
Procedure
2. Click Administration.
3. Click Variants.
See the Propagation section for details on how to configure Variant Management so that the selection of
Variant Work Items is determined by the relations to their parents and their parents' restrictions.
Use different configurations for all Variants via Work Item custom fields
Procedure
2. Click Administration.
A Variant custom field should already exist in a Project created from a template that supports
Variants, but if it wasn't, create one as follows:
a. Click Create new configuration.
b. Select the Variant option and click Next.
7. Exit Administration, expand the Work Item , select Variant and select a Variant from the list.
8. The Custom Fields section of the Variant now includes options to add a Feature Model and Master
Projects that only apply to the selected Variant.
The legacy configuration via the definitionProject Custom Field that defines what project both the
Feature Model and Master Specifications should be loaded from is still supported, but we recommended
using one of the two options above.
The comparison feature works the same as for single-project variant management. Open a Variant that
has the Definition Project field set to a different project, and click Compare Variants in the Feature
Selection section of the Work Item Editor. Compare Variants shows all Variants that have same project
selected in the Definition Project field.
Propagation
If configured, then the selection of Variant Work Items is determined by the relations to their parents
and the restrictions of these parents. The restrictions can only be managed on the highest level of the
hierarchy, not on all levels manually. Therefore:
• A child item with no restriction that is linked to a parent item is included in the generated variant
specification if its parent item is included. Its restriction is evaluated as TRUE.
• A child item with a restriction that is linked to a parent item:
◦ Is included in the generated variant specification if both the child and parent's restrictions are
evaluated as TRUE.
◦ Produces a validation error if its own restriction and its parent's restrictions are evaluated differently.
When using the propagation of Work Items into a variant selection on existing data sets, the complexity
of the migration can be substantial. By default, the variant evaluation reports an error if propagation and
restrictions contradict each other because the data is not consistent.
To simplify the adoption of propagation, it's possible to allow this inconsistency by setting the following
property to true in the polarion.properties file.
com.siemens.polarion.purevariants.propagationDeterminedByRestriction=true
When set to true, propagation is determined by restrictions. If there is a conflict between propagation and
restrictions, then the restriction is honored instead of throwing an evaluation error.
Warning
This behavior also has a consequence: If a child Work Item in the document structure is included into
the variant selection via propagation, then its parent Work Item from the Document structure is also
included, even if its restriction does not allow it.
Tip
Only use this property during the early adoption of propagation and remove it as soon as your data is in
a consistent state.
Configure Propagation
2. Click Administration.
3. Click Variants.
Note
The Propagation of Referenced Work Items:
Under Propagation, when selecting the Work Item link roles to include, you can also generate from
documents that contain referenced Work Items. If you do, then the configuration is taken from the
Project that contains them.
The Variants topic of global and project Administration enables administrators to restart the Polarion
VARIANTS back-end server and clean up the data. The Initialize Server button launches the operation.
This action should rarely be needed. It should only be invoked to recover from unexpected Polarion
VARIANTS Server data corruption, for example, caused by a power outage.
Appendix
Warning
Beginning with Polarion version 2015, this feature is replaced by Pages. You should create all new
reports and informational pages using that feature, rather than Classic Wiki (formerly called just "Wiki").
Classic Wiki will be supported through the version 2015 release cycle, and possibly longer. If you have
any reports or informational pages that you anticipate needing in the long term, you should plan to
recreate these using LiveReport or Info Pages.
Polarion features a built-in Wiki where users can create whatever content they need to support their
projects and collaboration. There is a default wiki space for the repository, and a default space for each
project, created when the project is created. In projects, you can create additional spaces to help organize
your content. For example, you might have one space for guidelines, and another for meeting notes. The
wiki provides a highly flexible communication medium accessible to everyone with access permissions for
Wiki pages. Wiki pages are stored and versioned in the underlying Subversion repository just like any other
development artifact.
The Wiki is fully integrated with other features of the platform, so it is quite easy to pull information from
other areas such as the Work Items tracker and display it in useful ways in Wiki pages. A robust library of
macros is provided that makes it simple to embed complex information. A complete reference for these
and as well as Wiki mark-up syntax is provided online in the Wiki Editor.
This chapter explains the major features of the Wiki. Most interaction is fairly standard. If you have used
other Wikis you should have no difficulty working with the integrated Wiki, especially if you use the
rich-text editor which is available for working with non-scripted Wiki content.
The entry point of each Wiki space is its Home page, which appears in Navigation under the space name
the Documents and Pages topic. Within each Wiki space you can add Wiki pages, and/or create
additional Wiki spaces, and Wiki pages within those spaces. The Help topics in this section explain how.
As you develop pages, you will probably embed links to other pages. In any page, you can find what other
pages are linked to the one you are viewing by clicking the Backlinks button on the toolbar (click Expand
Tools) to expose the Backlinks section of the page. This section lists all pages linked to the current page
and provides links to each one.
Page types
1. Content pages
2. Portal pages
3. Active pages
Content pages are analogous to web pages, while Portal pages are analogous to documents. Content
pages can contain dynamic content via use of macros (which can make use of queries). Portal pages have
content that is essentially static in nature. Active pages contain Velocity or Javascript code and cannot be
edited using Rich Text mode.
You can specify a page's type when you edit it in the Wiki editor. See Editing Wiki Pages. The default type
for a new page is Content page.
The Wiki is available in both the Repository scope and project scope.
1. In the Open Project or Project Group dialog, select either Repository, or select a project, and open
the selected scope.
2. In the Navigation pane, expand the Documents and Pages topic. The Default Space topic
appears which gives access to the default Wiki space. If you have created other Wiki spaces, they
appear as child topics under the Documents and Pages topic. (Documents also appear in the
Documents and Pages Navigation topic.)
Tip
When hovering over the Smart Title of a Wiki Page in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Wiki Page link with its Title as the link's label.
When multiple Wiki spaces exist in for the current scope (repository or project), they appear as child topics
of the Documents and Pages topic in Navigation. Click any Wiki space name in Navigation to navigate
into a different Wiki space. The node expands and the Navigation focus shifts to the Home topic of the Wiki
space you selected.
Note that if you click on Default Space, the Navigation shifts to the main Home topic - as the project's
Home pages is also the main page of the Default (Wiki) Space.
There are two main ways to locate and access Wiki pages: browsing and searching.
Browsing page names in Navigation is available if the space doesn't contain too many pages. In this case,
you can just click on the name of a listed page to navigate to it. If there are too many pages to display in
Navigation, (generally more than 20), you can click the Too many documents... text in Navigation to load
the space's Index page. The Index page provides a table of all the content in the Wiki space in alphabetical
order by name. The name of each item in the table is a clickable link to that item. The table in the Index
page can be sorted on different columns by clicking on the column headers. The Index topic appears in
Navigation when there are not too many items in the space, and you can click it to access the Index page.
When your Wiki contains many pages, searching may be the best way to find what you want. Start at the
Search box in Navigation. For information, see Search the Wiki.
You can create Wiki Spaces as needed for different types of discussions and collaboration. You can think of
Wiki spaces like folders in other applications.
In each space, you can create as many pages as you need. (You can also create Documents in spaces.)
Procedure
1. Open the project that you want to create a new Wiki Space for.
2. In Navigation, select the Documents and Pages topic. The project Wiki's main page appears.
3. Click on the page's toolbar and select Create New Space on the right. The New Space
dialog appears.
4. Enter a title and name for the new Wiki space in the Space Title and Space Name fields.
(Name is the system ID and can contain only ASCII characters.)
5. (Optional) Select another Parent Space to create the Wiki Space in.
6. Click OK.
The new Space title appears in Navigation, and the new Space's Home page opens with default
content, for you to edit and modify.
What to do next
Tip
You can also create a new Wiki Space using the New... item in the Actions menu on the Home
page of all Wiki Spaces.
Procedure
1. Use the icon found on the toolbar of each space's Index page, and choose the Classic Wiki
Page option.
It doesn't matter which Wiki space you are in currently when you invoke the New operation. You can
specify the name of the target space for the new page in the Create Classic Wiki Page dialog.
2. Edit any Wiki page and create a link a page name that does not yet exist, and then save the edited
page and click the new link.
If you did not specify a space name in the link, the new page will be created in the same space as the
page containing the link. Otherwise, the new page will be created in the specified space.
Tip
When creating a new Wiki page, the Name field is the page's system identifier (ID). It must be unique
within the space, and only ASCII characters are allowed.
The Title field is a human-friendly title that can contain non-ASCII characters. If specified, the value of
Title appears in Navigation. (If not specified, the value of Name appears.) You can modify the Title any
time using the Change Title action on the wiki editor toolbar.
When hovering over the Smart Title of a Wiki Page in the Navigation Header, a copy icon appears.
Using the icon allows users to copy the Wiki Page link with its Title as the link's label.
Procedure
You can use the Extract Work Item feature to create a new Work Item from some selected content in a Wiki
page. This is useful when you have been using the Wiki to collaborate on some content like requirements
or test cases, and you now want to have these tracked as Work Items so they can be managed with
workflow, assigned to people and Time Points, planned and schedules, and so forth.
Procedure
1. Navigate to the wiki page containing the content that you want to extract into a new Work Item.
The Title field of the new Work Item is filled in with the first sentence of the selected text, up to first period
character, or first 20 words. If there is no period among first 20 words, the entire selection is written into
the Description field and you should supply content in the Title field.
After you Save the new Work Item, the Tracker frame disappears. A link to the new item now appears at
the point where you began selecting content. You can click this link to navigate to the Work Item in the
Work Items topic, Table view. In the Hyperlinks section of the Work Item Editor, you will find a link to the
wiki page from which the Work Item was extracted.
If at some point you want to remove the generated Work Item link from the wiki page, you can do
so by deleting the generated macro using the Wiki Markup editor. In the editor look for {workitem:
projectid/workitem-id} where projectid is the ID of the project containing the linked Work Item,
and workitem-id is the ID of the linked Work Item. Delete this tag and save the page to remove the link.
The link no longer displays in the wiki page. Only the link is deleted - the Work Item created from the wiki
page content (using Extract Work Item) cannot be deleted except in the Tracker or Document (see Delete
Work Items). The Work Item will still contain a link to the wiki page in the Hyperlinks section of the Work
Item Editor. You can delete the hyperlink from there if you wish.
Once Wiki pages have been created, you can use the Wiki editor to create and modify content. There are 2
options for editing their content:
Access to editing is hidden by default. Click Expand Tools to expose the wiki page toolbar at the top of the
page. Click the Edit button to launch the Wiki editor. The editor opens in the default mode "Wiki Markup",
i.e. text-based editing using Wiki syntax.
When you open the Wiki editor, the Rich Text button appears on the button bar at the top of the editor
pane. Click this button to switch to Rich Text (WYSIWYG) mode. You can switch back to plain text mode
using the Wiki Markup. You can switch between the two modes any time.
Note that pages containing Velocity macros or other scripting do not show the Rick Tex button and cannot
be edited in Rich Text mode.
If you are not familiar with Wiki syntax, the Rich Text mode is a good way to get started creating Wiki
content. This mode does not currently support all content creation and editing features however. For
example, to add images you must use the plain text (Wiki Markup) mode. You cannot use this mode to
enter Velocity, Javascript, or HTML/CSS code. The embedded Wiki syntax help provides information and
examples for these and other elements and constructs.
In Rich Text mode you can format text content with graphical controls similar to those found a word
processor application. These controls appear on the Rich Text toolbar (shown at the top of the editor pane
when Rich Text mode is active). The toolbar currently provides these capabilities:
To create links to other content, you must use the Wiki syntax for links. Rich Text mode provides the
possibility to create links to other pages without switching back to Wiki Markup mode. When you click the
Internal Link on the editor toolbar, a placeholder link construct is inserted to the page. Please refer to the
embedded Wiki syntax help that appears when you edit pages.
Add Attachments
The Attachments section is available in Rich Text mode, enabling you to add or remove attachments
to/from the currently edited Wiki page. Note that before you can insert images in text, you must add them
as attachments. See working with attachments for more information.
This edit mode enables you to format text, create links, display images, and perform other editing
operations using standard XWiki syntax. You can also enter Velocity macros and scripting, Javascript, and
HTML/CSS code. This text-based editing is the default mode when you click the Edit button in the toolbar
of each Wiki page.
Note that in pages that support Rich Text (i.e. they contain no scripting), you can switch between the
Wiki Markup and Rich Text (WYSIWYG) mode any time during an editing session. You can use the Preview
button to see how your unsaved edits will look in the wiki page after saving.
The Wiki Syntax Help link appears at the right-hand side of the screen when the Wiki editor is active in
Wiki Mark-up mode.
The panel displays a number of labeled bars which represent different Help topics. The categories are for
different document elements, formatting, and macros for embedding tracker and other dynamic content in
wiki pages.
Clicking on any of the category bars expands it to reveal the syntax Help for the selected category.
This embedded help provides basic help for most editing tasks. More comprehensive syntax help is
provided in a special wiki page. To access this page, look for the Detailed Syntax Help link at the bottom
of the embedded syntax help in the Wiki editor. You can bookmark that page in your browser for future
reference.
Display images
You can display images in Wiki pages after they have been uploaded as attachments. Use the Attachments
section to upload your image file(s) and save the page. Then use the "Insert placeholder {image}" button
on the toolbar to insert the syntax for an image reference at the desired place in your text. Replace
image-attachment-filename.ext in the inserted {image} macro with the file name and extension of
an attached image.
Create tables
The {table} macro renders a table in the Wiki page. Table rows and columns are defined between two
{table} elements. Each line represents a row. Columns are separated by a vertical bar character (|). The first
line may be optionally defined as the table header.
Various parameters of the {table} macro provide control over some formatting. The id parameter,
if specified, causes the value to be rendered in the "id" attribute of the table's HTML. This can be
subsequently referenced in scripting.
For more specific information, consult the Tables section of the Wiki Syntax Help in the Wiki editor.
You can attach files of any type to a Wiki page in the Attachments section. The page section is hidden by
default when you are reading a page. When hidden, or if visible but scrolled out of view, you can jump
directly to it by clicking the Attachments button on the Wiki page toolbar. Graphical controls are provided
for adding and removing attachments.
Tip
You can also add attachments with previews to Pages, Documents and rich text fields.
After attachments have been added to a Wiki page, you can see their links in the page and optionally
download them to your local system. Images must be uploaded as attachments before they can be
displayed in the page content.
By default, the maximum file size of attachments is limited to 50 MB. The limit is configurable in
Administration.
Procedure
1. When viewing (i.e. not editing) a Wiki page, click the Expand Tools Attachments to expose the
Attachments section. Any existing attachments are listed in a table.
2. Click the (Edit) icon at the bottom left corner of the Attachments section. The graphical controls to
add an attachment appear.
3. Enter a title for the attachment. (Spaces not allowed.)
Note
Unsupported characters in attachment names will either:
• Prompt an error message.
• Be replaced with _ (underscores).
5. If you want to add another attachment, click the icon in the same row and repeat the previous
step.
6. After adding all attachments, click the Save icon.
Note
Your system or project administrator can optionally limit attachment file size. Contact your
administrator if you are unable to upload an attachment due to a size limitation.
You can update an existing attachment in the Wiki Markup editor or the Rich Text editor. You do this
by adding an attachment in the Attachments section of the editor and checking the Update existing
attachment option on the row of the new attachment. The file you upload for the new attachment must
have the same file name and extension as the existing attachment you want to update.
If an attachment is no longer needed, it can be removed from a Wiki page. In the table of attachments
in the Attachments section, click the icon on the row of the attachment you wish to remove. The
attachment is removed from the page when you save the change. It still exists in the page's history and
can be accessed there.
In the Attachments section, locate the attachment you want to download in the table of attachments. The
file name of the attachment appears as a link in the File Name column. To download the file, right click
on the file name and choose the command that saves a remote file to your local system. For example, in
Firefox choose Save Link As.
This section documents the supported attachment file types searchable by their content and metadata.
Generally, every attachment is indexed by its metadata: file name, file extension, author ID, author
name, update date and file size. The content of attachment file types listed in this topic is also indexed,
and therefore searchable, unless otherwise noted.
• attachments.indexingOfAttachmentContent.additionalFileTypes
• attachments.indexingOfAttachmentContent.fileTypesToIgnore
Polarion uses the Tika library for indexing. Only the file types supported by this library can be parsed. For a
complete list of those types, please consult the Tika documentation.
Warning
Polarion selects files to pass to TIka based on file extension (excluding the period character), but Tika
indexes files based on analysis of their content, not their file extension. Therefore, files with an incorrect
file extension lead to the indexing of an unwanted file, or exclusion from indexing of a desired file.
apxl, asp, aspx, c, cc, cpp, cxx, doc, docm, docx, dotm, dotx, dwfx, epub,
fb2, fbz, groovy, htm, html, ibook, java, key, mbox, mdb, mpp, msg, ncx,
numbers, odc, odf, odft, odg, odi, odm, odp, ods, odt, ole, opf, otc, otg,
oth, oti, otp, ots, ott, p7c, p7m, p7s, pages, pdf, pot, potm, potx, ppa,
ppam, pps, ppsm, ppsx, ppt, pptm, pptx, pst, pub, rfc822, rtf, sldasm, slddrw,
sldm, sldprt, sxw, tnef, tsd, txt, vsd, vsdm, vsdx, vssm, vssx, vstm, vstx,
wp6, wps, xht, xhtml, xla, xlam, xlr, xls, xlsb, xlsm, xlsx, xlt, xltm, xltx,
xlw, xml, xps
In general, any other file extension not included in General categories indexed by default (above), such
as media types.
Note
To have csv files indexed with content, an administrator must add the csv extension,
and any other extensions for this file type that users may attach, to the system property
attachments.indexingOfAttachmentContent.additionalFileTypes.
Caution
Archive files, such as zip, are not included in the default list of content-
indexed file types. If you choose to explicitly add such file types in the
attachments.indexingOfAttachmentContent.additionalFileTypes property, all file types
contained in archive attachments that are supported by the Tika library will be indexed.
The wiki has a number of macros that can be embedded in wiki pages using the Wiki Markup editor. Some
macros merely provide formatting - the {code} macro for example. Others provide content structures
such as tables, or display an image. Still others provide content from the tracker or the system which is
dynamically retrieved, formatted, and displayed in a wiki page. Such dynamic content may include subsets
of Work Items, or information about project users, or links to other projects and their wiki content.
This section covers several of the most commonly needed macros. The full listing is provided in the
embedded Wiki Syntax Help, accessible from the Wiki editor.
The {project} macro can be used to get a link to Polarion project. You can find more details and usage
examples in the Projects topic in the Wiki Syntax Help, available in the Wiki editor while editing a wiki
page.
The {workitem} and {workitems} macros can be used to extract information about, and create links
to Work Items. The {workitem} macro retrieves a single item. {workitems} retrieves multiple items.
The content returned, and the format, can be controlled via several parameters, including a parameter that
can contain a simple or complex Lucene query, and a parameter than can contain a SQL query (see next
section). You can find more details and usage examples in the Work Items topic in the Wiki Syntax Help,
available in the Wiki editor while editing a wiki page.
Polarion has an embedded SQL database layer that can facilitate Work Item queries in traceability reports
and other complex reports in Wiki Pages where a Lucene query would be highly inefficient and consume
undue time and system resources, or not work at all. For example, you could not readily formulate an outer
join in Lucene, but it's easily done with SQL. Primary storage of artifact data remains in the Subversion
repository, but the SQL layer maintains a special read-only index of the content which can be queried in
the {workitems} macro. Results of the SQL query can be read by all users using any license (assuming
they have read permissions for project wiki pages).
Note
Invalid SQL commands and symbols: (Implemented for security purposes)
• Some SQL commands and symbols are not allowed in SQL queries.
System Administrators define what's invalid in the polarion.properties file with the following
property:
◦ com.polarion.platform.sql.invalidCommands
• Exceptions from PostgreSQL are not propagated to client-side error messages. Instead, they are added
to the logs as ERRORs.
• See the default list for this property by searching for it in the System Configuration Properties
Reference document.
You can include the sqlQuery parameter in the {workitems} macro to execute a SQL query over Work
Items. When this parameter is used, other parameters that can also be used in the macro are limited to:
• display
• expand
• top
• fields
• width
• height
EXAMPLE:
{workitems: sqlQuery=
SELECT WI.C_URI
FROM WORKITEM WI, PROJECT P
WHERE WI.FK_URI_PROJECT = P.C_URI
AND P.C_ID = 'drivepilot'}
(Will work on the Drive Pilot demo project. Replace drivepilot with your Project ID to try it there.)
Note
If a query's processing exceeds limits set in the system configuration, it may be halted, and a notification
sent to the system administrator in order to prevent other users updates from being blocked by long-
running queries.
Tip
The graphical Query Builder in the Work Items topic contains an element SQL. It can be used alone to
filter the Work Items table by a SQL query only, or in conjunction with other visual query elements. As
with all Query Builder queries, the visual query is transformed to a URL, and can optionally be converted
to text via the Query Builder's drop-down menu.
The SQL element can be useful if you want to open result of the {workitems} macro filtered by the
sqlQuery parameter in the Work Items table, instead of entering a fully expanded query with IDs. For
more information on using the graphical Query Builder, see Construct Queries Graphically.
The {users} macro returns a list of users for a specified project. The content returned can be controlled
via several parameters, including a parameter that can contain a simple or complex query. You can find
more details and usage examples in the Users topic in the Wiki Syntax Help, available in the Wiki editor
while editing a wiki page.
The macro generates a table of content based on the headings in a wiki page. The content returned can be
controlled via several parameters. You can find more details and usage examples in the Headings topic in
the Wiki Syntax Help, available in the Wiki editor while editing a wiki page.
This macro renders a list of pages in a project or project group. For parameters and example, see the Pages
topic in the embedded Wiki Syntax Help in the Wiki editor.
This macro displays the stream of activity occurring on your Polarion portal. The Activity Stream is similar
to the news feed feature on social media sites. The macro's parameters enable you to restrict the amount
of information displayed. For details, see the Activity Stream topic in the embedded Wiki Syntax Help in
the Wiki editor.
Users of wiki pages displaying the activity stream can enter a query to filter the stream to restrict the
display to some specific information. Users can optionally click the provided link to open the item that
triggered the Activity (Work Item, Build, etc.)
Administrators can tune the system configuration to control the age and/or number of activities
maintained in the history. See: Properties for Activity Stream.
Macros such as {workitems} provide a parameter query in which you can specify a simple or complex
query to retrieve data. The query syntax can be copied from a visually constructed query in the Query
Builder, found in the Table and several other views in the Work Items topic. (See Search Work Items).
For example, you can use the {workitems} macro to display a listing of unresolved blocker and critical
defects on a wiki page by specifying a query as shown in the following listing:
You can use the Query Builder to construct the query and then copy the query parameter shown in the
page URL into the macro's query parameter.
Queries can specify which fields should be displayed in the results by including the fields in the query. For
example, the following query will display only the Work Item ID, Title, and Severity fields in the results:
Note
the fields parameter must reference field ID, not field label. Field IDs are case sensitive and do not
contain spaces. For example, for the field that logs time spent on a Work Item, a macro query must
specify time_spent (the field ID), and not Time Spent (the field label).
The same is true in the sortby parameter which specifies on which field the results should be sorted:
specify the field ID, not field label. Example:
The rule of thumb is that any macro parameter that references one of more Work Item fields must contain
field ID(s), not field name(s).
Polarion includes the FusionCharts free library that provides many types of charts. Usage is outside the
scope of Polarion documentation, but the library's documentation is bundled into distributions. You can
find a link to it in the Dashboard topic of the Wiki Syntax Help (accessible when any Wiki page is in edit
mode).
Users of the Polarion Java API can extend active wiki pages by means of Apache Velocity (see http://
velocity.apache.org/engine/1.4/user-guide.html). For information about Velocity variables available via
the API, see: Velocity Variables for Active Wiki Pages.
A major use case for dynamic-content wiki pages is reporting. For example, a page can be created to show
all unresolved critical-severity items for some time point. That can be useful, but what if a report consumer
wants to see unresolved critical-severity items for different time points, or assigned to different users?
It is possible, of course, to create separate pages, or separate sections in pages to report on each different
set of parameters. But it would be more useful to enable the report consumer to interactively change
some key parameters using simple graphical controls and obtain variant results. Polarion provides this
functionality through a set of parameterization macros. Users who know how to code wiki pages can easily
create report pages for less technical users, enabling them to create variant output for the same basic
report, which they can optionally export to PDF just as with any wiki page.
Parameter Macros:
Polarion provides the set of parameter* macros which enable you to create interactive report pages:
• {parameter} - declares a parameter of a specified type and value(s) which can be referenced in other
elements on the page.
• {parameter-form} - declares the start and end of an interactive part of the page which displays
interactive "widgets" or controls rendered by other macros of this group.
• {parameter-editor} - displays an edit control in which user can edit the value(s) declared in a
{parameter} statement.
• {parameter-form-submit} - provides a button widget for submitting user changes to one or more
{parameter-editor}s. This macro is available in Baselines.
• {parameter-form-save} - provides a button widget for saving user changes to one or more
{parameter-editor}s, overwriting current values in the respective{parameter} declaration(s) in
the page source.
The {parameter} and {parameter-editor} macros take one or more arguments. The complete
syntax reference is provided in the embedded Wiki Syntax Help (click Detailed Syntax Help at the bottom
of the Syntax Help pane in the Wiki Editor).
The {parameter} macro enables you to define a parameter which can be subsequently referenced
in other page elements... in the query argument of a {workitems} macro, or the id argument of a
{parameter-editor} macro.
You should declare all the {parameter}s for the page first, before any other page content.
You can then reference any declared parameter by appending its ID to the $pageParameters variable
following a period character (".") delimiter.
Examples:
Here is an example of a report page reporting on Work Items with user-selectable team, Work Item type,
resolution, and Work Item update dates:
##Parameter Definitions
{parameter:team|type=string|value=teamX|allowed-values=teamX,teamY}
{parameter:query|type=string|value=type:defect}
{parameter:justOpen|type=boolean|value=true}
{parameter:teamX|type=user|value=mTest,aSeller|multi=true}
{parameter:teamY|type=user|value=sDeveloper,pGUI|multi=true}
{parameter:dateFrom|type=date|value=2011-05-05}
{parameter:dateTo|type=date|value=@current}
{parameter-form}
Select Team: {parameter-editor:team} \\
Query: {parameter-editor:query} {parameter-form-submit} \\
Not Resolved: {parameter-editor:justOpen} \\
Updated from {parameter-editor:dateFrom} to {parameter-editor:dateTo} \\
{parameter-form}
#if ($pageParameters.justOpen)
#set($queryOpen = " AND NOT HAS_VALUE:resolution")
#end
For more examples, review the E-Library project that ships with Polarion. You can open it like any other
project, assuming that your administrator opted to install sample date when installing your Polarion
system.
Polarion integrates the Highcharts library, which enables users to easily create and show various types of
simple and complex charts in wiki pages, including Dashboards. You can implement these charts using
special Highcharts code. Chart types are documented with examples in the embedded Wiki Highcharts
Help. You can access this help via the embedded Syntax Help in the Wiki Mark-up Editor, or directly by its
URL in your Polarion portal.
Procedure
What to do next
Alternatively, you can go directly to the Wiki Highcharts Help on your system using this URL:
http://[HOST SERVER].[DOMAIN]/polarion/#/wiki/Doc/HighchartsHelp
(Where [HOST SERVER] is the name of your Polarion server, and [DOMAIN] is your internet domain.)
Example: http://polarion1.yourdomain.com/polarion/#/wiki/Doc/HighchartsHelp
You can export the content of Wiki Pages to Portable Document Format (PDF).
You can save the generated PDF to any accessible storage (local or network).
The content of the header and footer in generated PDF documents is configurable in Administration,
either globally for the repository, or for a specific project. Headers/footers can include such information as
the page name, history revision number, creator's user name, the export date, current page number and
total number of pages (for example, 7/20). For information, see: Configure PDF Export.
Tip
The configuration for PDF headers/footers changed significantly in Polarion 2011. If you update from
an earlier version in which you configured PDF export for Wiki Pages, you must reconfigure it in your
current installation. See: Configure PDF Export.
Procedure
2. In the page toolbar, click and select Export to PDF in the drop-down menu.
The Export to PDF dialog box appears.
4. Save or open the exported PDF. (Options will vary depending on your browser and operating system's
PDF settings.)
Tip
You can also export any historical revision of a Wiki Page to PDF. Open the Wiki Page's history, click on
a revision number, then click Export to PDF in the menu.
You can print the current Wiki page to any accessible printer.
Procedure
It can be faster to locate Wiki pages using the Search field at the top of the Navigation pane. However, you
need to have some idea of the page name you want to access... at least the first several characters. Typing
in the Filter box starts an incremental search of all the content in the project. You can limit the search to
the Wiki. After typing one or more characters in the Search field, the Navigation panel presents options for
limiting search to different types of content.
You can also search for Wiki content using the global search. Type some text in the Search field and press
your Enter or Return key. In the search results page, click the Wiki link to filter the results for Wiki pages
only.
The search results page provides controls to refine your search or start a new search.
The Polarion Wiki uses the underlying Subversion repository to store Wiki content. Consequently, the
content is versioned and history is maintained just as with other artifacts in the system.
Each time a Wiki page is changed and saved, a revision is created in the repository and added to the
history.
Procedure
The History shows all revisions of the current page. There you can access any revision of the page,
compare revisions, roll back changes, and access revisions of any attachments.
Revisions are listed by revision number. Revision numbers are clickable, and lead to the specific revision
of the page, including any attachments, links, etc. Revision numbers will not necessarily be sequential, as
they are for the repository as a whole, not for the specific Wiki page. The most recent revision appears first
in the table.
1. Navigate to the Wiki page whose revisions you want to compare and click the History toggle button in
the page toolbar to show the table of revisions.
2. In the left-hand column, check the boxes on the rows of the two revisions you wan to compare. (You
can only check two boxes at a time.)
3. Click the Compare button at the top of the page. The comparison page loads in your browser.
The page displays counts of things that were added, changed or deleted between the earlier and the later
of the two revisions being compared. Two buttons labeled Previous and Next enable you to navigate
among the changes in the page, enabling you to easily see what changed and how.
Three buttons at the top of the page enable you to select different views of the comparison. The default
is Page. When selected, you see the what the compared pages actually look like in the wiki. The Source
shows you the underlying wiki markup language, enabling you to compare changes that occurred there
which might not necessarily reflect when the Wiki page is viewed. The Attachments button enables you to
compare the attachments to the two revisions.
When you are comparing to Wiki page revisions, the Back to History button appears at the top above the
two revisions. Click it to exit the comparison and return to the table of revisions on the History view of the
page.
You can roll back the changes made in any revision of any Wiki page.
Procedure
Each revision of a Wiki page contains a version of any attachments. If attachments are added, removed, or
updated, a new revision of the page is created in the repository which includes the attachments current
at the time of the revision. Revisions of any Wiki page are shown in its History (see Finding a Specific
Revision).
To access the attachments for a specific revision, open the revision in the history (click on the revision
number), click the Attachments button in the Wiki page toolbar, and locate the attachment in the
Attachments section. Right click on the desired attachment and use the save link command on your
browser's right-click menu to download and save the attachment to your local system.
If the page author has included the {activity-stream} macro in the page mark-up, the portal Activity
Stream appears on the wiki page. The Activity Stream is similar to the news feed feature found on social
media websites. It displays a stream of activities taking place on the Polarion portal in real time. Activities
have different sources such as Builds, Work Items, and Plans. For more details, see the User Guide topic
Activity Stream.
As is usual with Wikis, users can update pages including updating of content and performing
administrative operations such as adding Wiki spaces and adding Wiki pages, and also deleting spaces
and deleting pages (below). However, in Polarion users must have permissions for these actions in the
scope in which the perform the actions (project, project group, or repository).
Procedure
1. Navigate to the page you want to delete so that you are viewing it.
2. Click the button in the toolbar and choose Delete on the drop-down menu..
3. Respond Yes to the confirmation prompt.
Tip
You can also delete a Wiki page from the Index page of the space in which the page resides. Check the
box next to the name of the page(s) you want to delete, and click the Delete button on the Index page
tool bar.
Procedure
1. In the Documents and Pages topic in Navigation, select the space you want to delete and then
navigate to its Index page.
2. In the toolbar of the Index page, click the drop-down actions menu (displays a gear icon) and choose
Delete Space.
3. Respond Yes to the confirmation prompt.
You can import tasks from Microsoft Project into a new or existing Polarion project to create Polarion Work
Items. You can also import MS Project milestones which become Time Points in Polarion. You should use
Microsoft Project's export feature to export a project to an XML file. You will need to have this file available
to in a location accessible to the computer on which you are accessing Polarion.
• Milestone summary tasks are imported as a Time Point and also as a Work Item, so that the grouping of
its subtasks is preserved. Ordinary milestones are imported as Time Points only.
• Imported milestone summary tasks and all subtasks are assigned to the corresponding Time Point.
• All predecessors of a Milestone task (recursively, including their subtasks and predecessors of subtasks)
are assigned to the corresponding Time Point. If more than one Time Point is found for a single task, the
earliest one is assigned.
• If all subtasks of a summary task are assigned to some Time Point, the summary task is also assigned to
a Time Point, i.e. to the one with greatest time found in any subtask.
• Custom Fields that are not configured are imported as the string type.
• Field mapping is as follows:
Procedure
1. Create a new project or open the project in which you want to import Work Items from MS Project.
3. Locate the drop-down menu control on the toolbar above the Work Items table in the Table view.
4. Click the control and select Import from the menu. The Import Work Items dialog appears.
5. If you want to import only Work Items, select Without User Creation.xml in the Configuration field.
If you want to import both Work Items and users, select Default.xml
6. Click the Browse button and use your file selection dialog to select the XML file exported from MS
Project.
7. Click the Start button to run the import operation and import the Work Items (and users if you chose
that option).
The procedure to begin the export is basically the same as for exporting to a document. When you
choose the option to export to MS Project, you have another option Export Time Points as Milestones. If
selected, the Time Points to which at least one of the exported items is assigned, are exported as milestone
tasks. Mapping of fields is the same as in case of import from MS Project.
Milestone predecessors are tasks that correspond to Work Items assigned to the relevant Time Point. Only
the minimal set of predecessors' links is created: predecessors of predecessors are not direct predecessors
of a milestone, and also subtasks of predecessors are not direct predecessors of milestones. Exported
milestones are always top level tasks. They are inserted at the first possible top level position after all items
that belong to the Time Point are exported.
Procedure
Note
Sort items by ID in ascending order:
If you want the output from Polarion to be exactly the same as the input from MS Project, then
items need to be sorted by ID in ascending order.
(It is not sorted this way in Polarion by default.)
3. Click the button in the toolbar and select Export in the menu. The Export Work Items dialog
appears.
4. Select the desired target format (xml: MS Project document) and character set and click OK. The
document will be created and readied for download. When processing is finished the Download
button appears in the dialog.
5. Click the Download button and choose the location to save the data file on your local system. The
selected data is saved in an appropriate XML format which you can subsequently open in MS Project.
The xml file that is created as a result of the Export to MS Project action should not be renamed with
a .mpp extension before opening it in MS Project.
Procedure
Procedure
1. Open MS Project.
2. Open the Open File dialog.
3. Choose xml format, select the xml file, and click Open.
4. Choose the As new project option.
Dialog boxes
The Create New Project dialog box presents several pages where you specify properties, template,
and other details about a new project. These pages also appear when the dialog box is invoked in
Administration to mark an existing repository folder as a project.
Basics page
ID Specify a unique identifier for your new project. Characters are restricted to: a-z, A-Z, 0-9,
underscore, dash, and period. No spaces.
Location Enter a Group Name (optional) in the first Location field on the left and a Project Name
in the Location field on the right.
(The Location and ID fields may be prefilled to a default value if configured in the system
properties.)
Select Click to launch the Select Project Group dialog box if you want to pick an existing
Project Project Group folder as the parent of your new project's folder.
Group
The folder name selected is added to the Location field on the left.
Tracker Specify a short string to be used as a prefix to the IDs of new Work Items created in the
Prefix project.
Caution
This prefix should be unique to your Polarion system. If it is duplicated, then citations
of Work Item IDs in commit comments may cause the revision to be linked to the
wrong item in the wrong project. For example, if two projects use the default prefix WI,
there could be two Work Items in the system with WI-3 as the ID. Then if a developer
references WI-3 in a commit message in an external SVN client, the revision will be
linked to the first Work Item found by the system having that ID, which may or may not
be the right one.
Template page
This page enables you to choose a project template on which to base the new project. Project templates
may provide any or all of various system configurations, workflow, repository folder structure, Documents,
Work Items, report Pages shortcuts, etc. — all customized to support a particular type of project.
Only templates enabled by your system configuration and supported by your license appear in the Create
New Project dialog box. For a listing of the default project templates, see: Default Project Templates.
Summary page
This page displays a read-only summary the details you have specified for the new project up to this point.
You have the opportunity to make changes before the project is created in the system. Click Previous to go
back and make any changes. When you are satisfied with the details, click Next to begin creating the new
project in the system.
Creation page
The Creation page appears when creation is complete. If any error occurred, it is reported here.
Tip
Administrators (or the user that created the project) can click Project Details to modify project details
and add a custom icon.
Invoked from: Open Project or Project Group item on the in the project menu on the Navigation
Header.
This dialog box enables you to access an information scope in which you want to do some work. This
dialog box enables you to:
• Access the current Repository to view dashboards, wiki and other information, or perform configurations
in this scope.
• Access any project group (in the current repository) to see dashboards, wiki and other information, or
perform configurations in this scope.
• Access a project to process Work Items, see dashboards and other information, or perform
configurations in this scope.
The left side of the dialog box is a tabbed content browser comprised of the following items:
All Projects Displays all the content in the current repository allowing selection of any project group or
project to open.
When a project is selected the Add to Favorites icon appears in the highlighted group
or project name. Click it to add the selected project to the Favorites tab.
My Projects Displays only those project groups and projects for which you have some role. Select any
available content to open it.
When a project is selected the Add to Favorites icon appears in the highlighted group
or project name. Click it to add the selected project to the Favorites tab.
Switch Flat/ Button appears to the right of the tab set and switches between hierarchical and flat
Tree presentation in the currently selected tab.
Scope Green box explains the icons used in this dialog box.
information box
Actions Displays a list of available actions you can invoke. For example, if you have
permissions to create a new project, the Create New Project link appears. If there
are no actions available given your user permissions, the section does not appear.
Switch Polarion Appears only if your Polarion system has been configured to work with multiple
Server repositories hosted on different servers. Displays a list of links for the currently
configured repositories. Click the name of the repository you want to access.
Favorited projects
You can easily access your Favorites projects by clicking beside the project name in the Navigation
Header.
Note
When adding a project to the Favorites list, it takes a couple of seconds for the new project to appear in
the list. If it does not appear, make sure to refresh the page.
Tip
The same Favorites list of projects is available for users when Branching Documents, Reusing
Documents, and Duplicating Work Item.
To remove a project from Favorites, click the (yellow star) icon next to the project in the list.
Invoked from: Navigation Documents and Pages , selected Document, sidebar, Work Item
Properties, Edit Links.
Suspect Toggles the Suspect property of the link. For information, see: Suspect Links.
Role The link role defining the relationship between the linked Work Items. (For information, see:
Edit Link Roles.) List contains the link roles currently configured for the project and which are
applicable to the Work Item type as defined in link role rules in the project configuration.
Title : Displays the ID and Title of the linked Work Item. The string is a link that leads to the linked
Work Item in the Table view of the Work Items topic. When adding a new link the edit field
accepts the ID or outline number of the target Work Item. Use ID to link to Work Items that
are not defined in the current Document. Outline number works only with Work Items defined
in the current Document. The icon in this column leads to a picker dialog in which you can
browse or use querying to locate the target Work Item for the link.
Project Displays the name of the project to which a linked Work Item belongs. Read-only.
Revision The repository revision of the target Work Item to which the source Work Item links. Normally,
links will point to the Head revision of the item, but you have the option to link them to a
specific revision number, either the current revision, or a specific revision which you explicitly
select in the picker dialog box.
Assignee Displays the name of the person(s) to which the linked Work Item is assigned. If no name
appears, the linked item is currently unassigned. Read-only.
Actions Provides icons enabling you to remove existing links or add new links to the Work Item
currently selected in a Document. The (Remove) icon is disabled when a link is structural in
nature, derived from the element structure of the Document. For example, if a Work Item is a
Heading 3 that is under a Heading 2, which is also marked as a Work Item, the two sections
have a parent-child relationship. The relationship is tracked with a link using the appropriate
link role. As this is inherent structure, the system maintains these structural links and does not
allow users to explicitly remove them via link editing. If the two sections were merged into a
single section, the link would be automatically removed.
Invoked from the Table view of Work Items (Navigation Work Items), Linked Revisions section,
(Select Revision) icon .
Use this dialog box to find and select a repository revision to link to the current Work Item, and enter the
revision number in the current line of the item's Linked Revisions section. Please refer to the following
figure:
Scope Users
The dialog box presents a query bar and a table of revisions found by the current query. Click on the
revision number in the table to select that revision as the link target and close the dialog box.
Query segments
The query bar has 3 controls that enable you to formulate 2 query segments:
Revision fields
Polarion indexes several fields for repository revisions, enabling you to query for values in those fields. The
following table lists these fields.
Message Text of the revision If all you want to find is some word or phrase in the commit
commit message message, you can skip entering this field name and just enter
the text you want to find. You can combine search on this field
with search on some other field. Example: Read only AND
created:20090628
Table configuration
You can configure which revision fields appear in the Revision Picker dialog box, in what order, and their
sorting order and direction. To invoke the Table Configuration dialog box, right-click on the header bar of
the revisions table (in the Revision Picker dialog box), and on the menu choose More.
Siemens Analytics
Information about the Digital product experience program is now added to Polarion. The main purpose
of the Digital product experience program is to provide information to the Customer Success Management
team about how well users are adopting Polarion.
You can choose to participate by setting the value for the Digital Product Experience setting to AGREE.
This setting is available under My Account Data Privacy. When you change the value of this setting, a
dialog box displaying more information about the setting is displayed.
When you initially log on to Polarion, the Help us improve Polarion... dialog box appears. It contains
information about the Product Excellence Program. To participate in the program, choose AGREE, then
click Save. For more information about the Product Excellence Program, click the Siemens Trust Center
link.
When you are logged on to Polarion, you can also change your preference for the Product Excellence
Program under My Account Data Privacy. You can either AGREE or DECLINE. When you change the
value of this setting, a dialog box displaying more information about the setting appears.
Note
The default setting for the Product Excellence Program is DISABLED. You can enable it using the prompt
during your first login to Polarion, or under My Account Data Privacy. See Updates to Siemens
Analytics functionality for more information.
Privacy Statement
The Product Excellence Program helps Siemens Digital Industries Software understand how customers use
our products and assists us in improving them. The program is anonymous, and participation is voluntary.
The Product Excellence Program is designed to protect user privacy and the intellectual property created
through the use of Siemens Digital Industries Software products.
The Product Excellence Program collects data about your installation, the features you use, and how
you use them. The data is sent to Siemens Digital Industries Software for analysis. By examining usage
patterns from a large pool of users, we gain insight into how Polarion is used and how to improve it in
future releases. Data collection occurs in the background as you use the software and does not affect
performance or functionality.
The data collected can vary by product and release as we gain more insight or add new capabilities. The
Product Excellence Program may collect information on the functions utilized, the operating environment
(for example, OS, RAM, graphics, and so on), product version, or other user interaction indications.
Siemens Digital Industries Software only uses this data to improve our products and is never shared with
any third party.
There is no contact information in the data, and Siemens Digital Industries Software will not contact you
by phone or email due to the data collected. Absolutely no information about the data you create or
manage is collected.
Participation is optional
You can opt out of the Product Excellence Program under My Account Data Privacy.
The following table provides examples of the type of usage data collected by Siemens Digital Industries
Software and, equally important, clarifies what data is not collected by Siemens Digital Industries Software.
Deprecated macros
This section documents Wiki macros that have been deprecated in Polarion. If deprecated macros can still
be used this will be noted in the relevant topics.
Miscellaneous macros
Macros noted in this section are deprecated and should be replaced as noted.
{includeForm} Macro
The {includeForm} macro enabled insertion into one wiki page of the content of another wiki page.
This macro was replaced in version 2016 by {include-page} and {include-macros}. See Classic Wiki
syntax Help for details on usage of the new macros.
Beginning with version 2012, the following Test Management macros were deprecated and removed from
the Wiki Syntax Help. However, the macros are still supported and can be used in Wiki pages.
{testruns} Macro
Parameters:
• query (optional) - query used to locate test runs to display (format of the query is the same as for
{pages} macro).
• top (optional) - maximum number of test runs to be displayed.
• fields (optional) - comma-separated list of test run fields to display. Supports the same fields as the
{pages} macro, and following additional fields:
◦ id (ID of a test run)
◦ owner (owner of a test run)
◦ statistics.<test result> (shows statistics for a specific test result), statistics.executed
(shows total number of executions) and statistics (shows statistics for all test results and total number
of executions).
• prefix (optional) - page name prefix of test run pages. Defaults to "TestRun_".
• testResultEnum (optional) - enumeration that contains all test results. Defaults to "testResult".
• sortby (optional) - IDs of the fields to use for sorting the test runs. Supports the same fields as the
{pages} macro, and the following additional fields: id and owner.
• project (optional) - project to load test runs from. Defaults to the current project.
• space (optional) - space to load test runs from. Defaults to the current project.
EXAMPLE:
{testrun-results:TestRun_123}
{testrun-results} macro
PARAMETERS:
• TestRun - name of the test run for which macro will display results.
• testResultEnum (optional) - the enumeration containing all test results. Defaults to "testResult".
• query (optional) - query used to find test cases that belong to this test run if they were not executed.
EXAMPLE:
{execute-tests-button:testRun=$testRun|
query=comments.title:"Test Blocked in test run:$testRunId"|
document=Testing/MainTestSpecification}
execute-tests-button} macro
The {execute-tests-button} macro renders a button which allows users to execute test cases.
PARAMETERS:
• testRun - name of the test run that defines the test cases to be executed
• document (optional) - name of a Document in which the test cases to be executed are defined
• query (optional if document is specified) - query used to filter the test cases to be executed
• project (optional if macro is used on project level) - project containing the test cases. Defaults to the
current project.
• sortby (optional, not available if document is specified) - IDs of the fields to use for sorting the test
cases. Supports the same fields as the {workitems} macro.
• testRunField (optional) - ID of the Work Item field that will be auto-filled with test run. Defaults to
"testRun".
• additionalFields (optional) - additional fields that will be auto-filled in the form "<field>:<value>,..."
4. Administrator's guide
Administration basics
Administration permissions
To access Polarion's administration interface you must have a user account that is granted administrator-
level access permissions. Access permissions are granted to a Role, which can then be assigned to user
accounts.
1. Global: administrator permissions for the entire repository, including all projects.
2. Project: administrator permissions for a specific project.
Tip
Administrators on Linux can grant users a basic level of Polarion administrative rights without giving
them system-wide privileges.
After a new installation there is one default user account with user name System Administrator which
has Global administrator permissions.
The default System Administrator account provides access to all Polarion administration and configuration
features for the Polarion system, to all projects in the integrated Subversion repository, and to the
repository itself.
Tip
It is good practice to periodically change the password for the System Administrator account. For
information about passwords in general, see Passwords.
The System Administrator may find it useful or necessary to grant administrator permissions to other
Polarion users. For example, if the main administrator is absent for some reason, someone else in
the organization should be able to perform all system administration functions with Polarion. Also, the
managers or leaders of projects can be given administrator permissions for the projects they oversee. This
enables them to perform such tasks as adding user accounts, assigning project user roles, and modifying
the project configuration and properties.
A prospective administrator must have a user account on your Polarion system. Some global roles should
already be assigned in the process of creating the user account. Some project-scope role assignments
may also exist on the account. To grant administrator permissions, you need to edit the user's account
and specify administrator role(s) for the Global scope, if applicable, and per project for project-scope
administrator permissions.
For information on creating user accounts and defining user roles, see Managing Users & Permissions.
To help ensure the security of your Polarion system, you should change the default password of the
System Administrator user account described below, and the password for the polarion user account of
the integrated Subversion (SVN) repository.
The default System Administrator user account has access to all administrative functions of Polarion,
including read-write access to the Subversion repository. After installing Polarion for actual production use,
you should change the password on the default System Administrator account. Before doing so, consider
creating another account with administrator permissions for yourself, and perhaps someone else.
Procedure
1. Log on to the Polarion portal with the default System Administrator credentials. (username: admin,
password: admin.)
2. Click My Polarion. The My Polarion page for the System Administrator account loads in the content
area.
7. When finished editing the System Administrator profile, click Save. The password is now changed
and you must use it next time you log on.
Warning
Do not lose the new password.
If you lose the changed password, you will not be able to log on as the System Administrator user. If no
other accounts exist with administrator permissions, it will not be possible to change the configuration,
add projects, manage user accounts, etc.
Administration interface
There are two ways that you can perform administrative functions in Polarion.
Most administration and configuration tasks can be done using the graphical user interface.
Administration scopes
Tip
There is another level of configuration that controls behaviors and functions of the Polarion platform
and features — the system-level configuration properties, coded into Polarion and modifiable in the
system properties file polarion.properties. This file resides on the server's file system (see System
Properties File Location), and requires editing outside of the Polarion portal. A number of common
system configuration tweaks using system configuration properties are covered in Advanced System
Tuning. The Polarion System Configuration Properties Reference document, available online on
Support Center, provides comprehensive reference information.
Configuration changes propagate from global to project scope according to these rules:
• Changes in the global configuration are propagated to existing projects unless they have a project-level
configuration for the same item. If they do, then the project-level configuration takes precedence.
• New projects may inherit the global configuration, but it depends on how their Project Template is set
up. If the Project Template defines project-level configurations for specific items, they take precedence
over the global configuration. Global-level configurations are inherited for items that are not specifically
defined in the Project Template.
• You can apply a project-level configuration globally, but you must copy it from the project and paste it to
the global configuration manually.
Warning
Do not remove any project-scope configuration file in order to use the respective global configuration
in the project. This will interfere with the system's ability to resolve inheritance and precedence. It can
prevent users from performing workflow actions, and cause other problems.
Either restore the original revision of the project-scope file from the repository, or if the global
configuration has changed since the original revision, copy the current global-scope file to the project's
repository location, overwriting the project-scope file.
Example: Suppose a Work Item type Defect. When looking for configuration settings for this type:
1. The system looks for configuration settings for the Defect type in the current project.
2. If none is found, the system looks for configuration settings for all Work Item types in the project.
3. If none is found, the system looks for configuration settings for the Defect type in the global
configuration.
4. If none is found, the system uses the settings for all Work Item types in the global configuration.
All administration functions are accessible via the graphical user interface (GUI) of the Polarion portal.
Most configurations can be performed using graphical controls in the portal. Where graphical controls are
not provided, configurations are performed by editing the respective XML configuration file, which can be
done on or off line.
Some administrative functions are performed by editing a relevant XML configuration file stored in the
repository. These configurations are generally less frequently modified by most Polarion users. Where some
configuration requires editing a configuration file, you have two options:
• Edit the XML file online using the basic text editor provided in the portal web interface.
• Download a copy of the configuration file to your local system, edit it locally, then Import from file to
upload the modified file back to the Polarion portal.
Download and edit locally. Import a locally edited Edit configuration online in
configuration file. portal.
Sometimes configuration or customization is possible both globally, and also for projects (or sometimes
project groups). Initially, there is no configuration file for the more granular scope. In this case, you can
download the global configuration file, modify it for the scope in which it applies, and upload the modified
file to the repository URL applicable for the scope, or, in some cases, to the same URL but with the file
renamed in a way that Polarion recognizes as applying to the more granular scope. Help texts are provided
in the portal page where you access to the configuration file, which indicate where you need to upload the
modified file, and/or how the modified file must be named to apply in a narrower scope.
You can create some project-scope configurations online without having to download/upload the XML
configuration file. Where this capability is available, a labeled control or link is provided creating a project-
scope configuration. Refer to help for individual configurations for specifics.
Quick Create comes preconfigured in Polarion, but administrators can customize the artifacts users can
create, the button and dialog box's name, and even the button's tooltip.
The Quick Create button is not available for baseline views, in the Administration user interface, and
for Project Groups.
The options under Quick Create are different if you click it under the Global scope. Using the default
configuration, you can:
• Create a Work Item. (Set up the project, Work Item Type, and destination in Administration before
you open the Work Item creation form.)
• Create a Rich Page.
• Create a Space.
The following properties are used along with a custom Rich Page to customize the Quick Create feature.
The relative path to the LiveReport that defines what options appear when users click CREATE... in
the Navigation Header.
(Create Work Items, LiveDocs, Plans, and so on.)
It applies to the current project context. It uses the global path name if nothing is defined in the project
context.
Example
◦ Project-level example: quickCreate.templatePath=spaceID/richpageID (Takes the
configuration from the current project.)
◊ You can specify a projectID (quickCreate.templatePath=projectID/spaceID/
richpageID) to use a configuration from another project.
◊ (You can even use projectID for your current project, but it is not required because the relative
path is enough.)
◦ Global-level example: quickCreate.templatePath=/spaceID/richpageID (The / at the
beginning indicates the global level.)
(For the Global level, you can also use a relative path, but if you want to reference the Global level
from a project you must use /spaceID/pageID.)
◊ Revert to default: Use quickCreate.templatePath=default to revert to the default Quick
Create configuration.
◊ Hide the Create... button: Use quickCreate.templatePath= (with no value) to hide the
Create... button in the Navigation Header.
◦ If you do not add this property then it behaves as if you entered a default value.
If the property is added but no value is entered, then the CREATE... button is hidden.
If you do not add this property, it behaves like you entered a default value. (It reverts to the default
Quick Create configuration.)
• quickCreate.buttonName
A custom name for the Navigation Header button:.
When clicked, it opens a dialog with the content defined in the quickCreate.templatePath
property.
The button label is CREATE... if this property is not defined.
We recommend using short (1-3 word), descriptive values.
It applies to the current project context.
It uses the global button name if nothing is defined in the project context.
Example: quickCreate.buttonName=CREATE...
• quickCreate.buttonTooltip
A custom tooltip for the Navigation Header button:
It appears when users hover over the button.
The tooltip is "Quick Create - Create new objects of any type from anywhere." if this
property is not defined.
It applies to the current project context.
It uses the global button tooltip if nothing is defined in the project context.
Example:quickCreate.buttonTooltip=Quick Create - Create new objects of any
type from anywhere.
• quickCreate.dialogTitle
A custom title for the dialog box:
(With content defined in the quickCreate.templatePath property.)
The title is Create New... if this property is not defined. We recommend using short (1-3 word)
descriptive values.
It applies to the current project context.
It uses the global title if nothing is defined in the project context.
Example: quickCreate.dialogTitle=Create New...
You can define what artifacts to allow users to Quick Create with Velocity using Java builder for JS Actions.
Tip
• See the Interface JsActionsBuilder section in Polarion's SDK documentation for a list of available
methods.
[POLARION_HOME]/polarion/sdk/doc/javadoc-rendering/com/polarion/alm/shared/api/utils/js/
JsActionsBuilder.html
• You can also download this QuickCreateDefaultTemplate.zip file and customize it.
• For a detailed description on the Quick Create Default Template configuration, see the Widget SDK
documentation.
(You can access the SDK documentation via your web browser by appending polarion/sdk/ to the
URL of your Polarion server.)
Example: http://polarion.mydomain.com/polarion/sdk/
You should use these methods as onclick attributes in Velocity HTML elements. (For example, <div>
elements.)
Note
• Users must have READ permission for Rich Pages to use Quick Create.
• If you do not want all users to have READ permissions but still see Quick Create, then you can set
permissions via a Custom Set for Pages.
(Import your page template into a Space and grant READ permissions for all users, but only for that
Space.)
• Permissions to particular actions are still valid for actions invoked via Quick Create.
The Quick Create Default Template configuration contains examples of context-dependent actions you
can use in the Quick Create dialog:
• In a LiveDoc context, you can create a Document Baseline for the opened Document, reuse the
Document, or branch it.
• Your users can create a sibling or child Work Item for the selected Work Item when working in the
following places:
◦ When they select a single Work Item that belongs to a Document from Table/ Tree views in the
Work Item Tracker.
◦ When they select a single Work Item in Table/ Tree view while working in a Document.
◦ If they are working with a Document Work Item in the Work Item form (editor).
◦ If the selected Work Item is not a Referenced Work Item.
(The current API creates a linked Work Item only in its primary Document. The action is disabled for
Referenced Work Items.)
◦ If the Document is not a historical revision.
Once you have created your custom configuration Rich Page, you must import it as a Page Archive.
Procedure
4. Click Choose File and select your customized Page.xml archived in a zip file.
5. Click OK.
Once the upload is complete, the file opens in Polarion's Page editor.
If you experience any problems, we suggest you try to look into the Log Files first.
If you see that some items are missing in the UI, or do not display correctly, consult the Index and Reindex
topic. The index repair and rebuild procedures described there can resolve many issues.
If you are still unable to resolve some problem, please contact Polarion technical support on Support
Center. It can expedite matters if you can provide the following:
Tip
On Linux you can use [POLARION_HOME]/bin/polarion.init tar-log to gather all relevant log
files.
The Polarion distribution includes a diagnostic tool that can gather and compile information from your
system for use by Polarion technical support engineers. The components and documentation are installed
to the folder [POLARION_HOME]/polarion/diagtool (Linux) or [POLARION_HOME]\polarion\diagtool
(Windows). It is recommended that you install and run this tool only if advised by a support engineer.
Administration topics
When you have administrator permissions for the scope you are working in (Repository or a project), the
Administration link appears in the tool view of Navigation. Click it to enter the administration interface for
the current scope.
When you enter the Administration interface, Navigation contains a tree of topics — links that take you
into various administration functions and provide access to configuration files and graphical interfaces
(where available). Nodes displaying a > symbol are administration categories. Clicking such nodes expands
them to show the available subtopics. Clicking a topic opens the page of relevant administrative function.
Most configurations provide a graphical user interface (GUI) that enable you to edit the configuration
visually. For example, Workflow and Enumerations have such interfaces. Some configurations require
editing the respective XML configuration file. When you select this type of topic in Navigation, the page
provides access to and information about the configuration file, and also embedded help text. Two options
for editing the configuration file are also provided:
1. Off-line editing: Links and controls are provided for downloading the current version of the
configuration file, and uploading the modified file back to the repository.
2. On-line editing: A basic text editor is provided that enables you to load the current version of the
configuration file, edit the XML directly in the portal, and commit the changes immediately.
Each of the available topics is documented in the Administrator's Guide. Reference information about data
fields, defaults, and other information is provided in the Administration Reference.
The following table lists the topics are available in the Administration interface:
Work Items Repository, Customization options for Work Items, including Work Item
project, types, fields, auto- assignment, workflow, voting, and many
more.
project group
(limited)
Documents & Repository, Configure Document and Page types, custom fields,
Pages project workflows, attachment size limit and PDF export options
Plans Repository, Define Plan custom fields, statuses and status semantics,
project configure Plan templates, permissions and more.
Repository, Configure Variants for existing projects, across multiple
Variants
project projects, Propagation, and back-end server administration.
Reports Repository, Configure report descriptors, Work Item metrics, and various
project reports.
Building Repository, Define build artifacts (project only) and descriptors, configure
project Work Item reports.
Repository, Configure how and when email notifications are sent to users.
Notifications
project
Maintenance Repository, Check and refresh indexes, clear system caches, and capture
project Thread Dumps of all Java threads.
Repository License assignment tools; license usage information.
License
Repository, Configuration of external repositories.
Repositories
project
The Administration interface helps you manage Polarion user accounts and permissions. If you have
global, Repository scope administrator permissions, you can access all user accounts in the system. If
you have administrator permissions for a project, you can access user accounts for users who are assigned
a role in the project you administrate.
Tip
Looking to grant REST API Endpoint permissions? See the REST API User Guide.
The User Management topic in the Navigation panel provides access to the following user
management functions:
• User accounts
• User groups
• User roles
• Repository access management
• Permissions
• LDAP synchronization
• User Account Vault
• User authentication management , to adjust settings for multiple users simultaneously. Visible only if
multilogin is configured.
• User authentication .Auto-create.
• User time splitting (between projects)
In a new Polarion system, it is typical for there to be more user accounts created than projects initially, so
an efficient approach is to define projects first. Then create user accounts, assigning each user to one or
more projects in the process. Finally, specify a project leader for each project.
When you create a new project, you can specify a user as the project lead. You must return to the project
later to specify a project lead if you have not created user accounts yet. When you create a user account
manually — that is, not via Auto-create from LDAP, SAML, OAUTH2 or by configuring Polarion to let users
self-create accounts — you can specify what projects the user can access. If you have not yet defined any
projects, you must return to the user account to assign any projects after the projects are added to the
system.
Authenticate users
There are several options for authenticating users who log on to a Polarion system. All but Simple
Password support single sign-on (SSO). Polarion can be configured to use more than one authentication
method. Administrators can create and maintain the configuration in the authentication.xml file, which
resides on the server's file system. Information on how to configure Polarion to work with the different
options is provided in the Authentication guide.
Caution
Beginning with version 21 R1, user authentication via the authentication.xml file is required. New
installations of version 21 R1 or later use it by default. Administrators updating from older versions
must update their system's user authentication configuration.
Simple password Locally stored user credentials stored in the password file. This method is
not single sign-on. This is the default for new installations.
LDAP Active Directory A widely-used SSO authentication method for network-authenticated users.
OAuth 2 Enables authentication of Polarion users by one or more third-party
authentication providers.
Security Assertion Open standard for authentication data exchange. Configuration is required
Markup Language (SAML) for new installations and for updated systems.
Teamcenter Security Allows users of Teamcenter to log on to Polarion using existing credentials.
Services (TcSS)
Kerberos A ticket-based network authentication protocol.
Administrators have several options for creating new user accounts in Polarion. After accounts are created,
they are accessible in Administration User Management Users. All user accounts in
the system are accessible when you are working in the Repository (global) scope. When working in the
scope of a project, only those users that have been assigned one or more roles in the project are shown on
the page.
If you just want to create a single new user, you can do it manually.
Warning
• The ID field must be a unique value in the repository and should not contain spaces.
Accepted characters: Upper and lower case letters, numbers, dashes, underscores, periods, and the
@ sign.
• The user's ID is saved with the exact upper and lower case letters as provided when the user's account
was created. This allows you to match the user's ID from Polarion with other integrated third-party
systems.
• Polarion is case-insensitive to user IDs when users log on. This allows a users to log on with any
case-insensitive variant of their ID. User IDs are still case sensitive in the API.
• New users must be assigned at least one Global role in the Global Roles section. Otherwise, they
cannot access any content in the portal.
• Log on permission is only granted to users assigned a role of user. By default, a new user is assigned
the role everyone. If you do not also assign a role of user, either at the repository level, or in
at least one project, the new user account is disabled, and the string [disabled] appears in red
text in the user's account page when the new user account is saved. (However, this only applies to
non-administrator users. Administrator users do not need explicit permissions assigned, because the
administrator role grants them all permissions in the scope.)
3. To create a new user for a specific project, open that project. Otherwise, select Repository in the
Open Project or Project Group dialog box.
4. In the Navigation panel, select User Management : Users.
5. In the Users table, click Create new User. A form for entering new user account information appears.
6. Enter information in the required fields marked with a red asterisk and any other information you
want to specify.
Note
If multiple licenses are present on your Polarion server, the License Type field appears on the user
account form. The field provides a drop-down list of the licenses currently available. Select the
license to be used by the new user you are creating.
You can configure Polarion so that users can reset their own passwords.
You can configure Polarion to display a link on the portal log on page that leads to some page you have
set up for users to reset their password. You need to set two system properties in the polarion.properties
system configuration file:
Note
For user accounts that originate from configured LDAP, SAML, OAUTH2 authentication sources, the
users' information should be updated on the authentication provider if there are any changes. You can
examine the authentication configuration to determine if user accounts are being created from these
authentication sources. For information, see Authentication guide.
Procedure
Note
Remember that the user account you want may not be on the first page of the Users table if there
are multiple pages. You can also use the Search field to search for the user's name.
After accessing the desired account, click Edit in the lower part of the page. The following fields are
modifiable:
• Name
• Initials
• Email
• Password
• Disable Notifications
You can change a user's password or configure Polarion so that users can reset their own passwords.
Procedure
Note
Depending on the user authentication configuration, the password fields may not appear, and you
may not be able to change the user's password in Polarion. In such cases, you can allow the user to
reset their password, or the password can be reset via the authentication provider.
For information about passwords and password characters, see Passwords.
Delete users
Repository administrators can delete user accounts provided that the users are not the Assignee of any
Work Items.
This is the only check before deletion. If a deleted user has created any Work Items, the deleted user's ID
appears italicized in the Author field of those items.
Caution
If Polarion is synchronized with LDAP, and a user is deleted via Polarion Administration, then the
user's LDAP account is not deleted. The user cannot log on to Polarion anymore, but can still access the
Subversion repository via an external client. Delete the user's account on LDAP if the user should not
have continued access to the repository.
Procedure
2. Go to Global Administration.
If you find a user that cannot be deleted, you need to locate the Work Items assigned to that user, and
either unassign or reassign the items.
Procedure
1. Note the ID of the user you wish to delete. Then open the Repository in Navigation. If you are in
Administration, click Return to Portal.
3. In the Table view, enter the following query string into the Query Builder: assignee.id:
[USER_ID]
In this string, [USER_ID] is the ID of the user you wish to delete. This query returns all the Work
Items in the repository for which the user is an Assignee.
4. For each item, unassign the user or reassign the item to a different user.
Note
Use Bulk Edit to select multiple Work Items, and apply the change of Assignee to all selected
items at once.
Run the query again to be sure there are still no Work Items assigned to the user.
After completing the steps, you can return to Repository Administration and Delete the user.
User roles control the portal content a user can access, and level of access they have to project artifacts
and data. For example, a someone assigned a project_admin role generally can make changes to project
artifacts, while someone with a project_user role would typically have read-only access.
What a user with a given role can access is controlled by the permissions configuration. In Polarion,
permissions are applied to roles, and roles are assigned to users.
User roles can be assigned in the repository scope, and in individual projects. Repository-scope roles
control permissions of users when they log on to the repository. Project-scope roles control permissions of
users when they log on to a project.
• User roles are configured in the User Management Roles topic in the Administration
interface.
• The level of access for each defined role is configured in User Management Permissions
Management.
Default Roles
Note
Polarion comes preconfigured with several default user roles for different scopes.
You can add or delete role definitions for the repository or a project. If you add a new role definition,
you need to configure permissions for it in User Management Permissions Management:
See Configure User Permissions. If you assign a role to a user without defining permissions for the role,
the user assigned to it cannot access anything in the repository. Also, access rights for the Subversion
repository should be adjusted for the new role in User Management Access Management, or
in the SVN access file directly.
Note
The Access Management topic is only available when using an ALM license.
Procedure
1. Log on with administrator permissions for the scope in which you want to define the new role, and
enter Administration.
2. If adding a repository-scope role, select Repository in the Open dialog box. Otherwise, select the
project for which you want to add a new role definition.
3. In Navigation, go to User Management and select Roles. The Roles administration page
appears, listing the roles currently configured for the scope in which you are working.
4. In the page toolbar, click Create New Role.
Note
This step is optional. You can assign the role to users at a later time.
8. Open User Management Permissions Management, click the By Role tab, and select
the new role you just created in the Role list.
9. Grant any permissions you want users assigned the role to have, and click Save.
Procedure
1. Log on with administrator permissions for the scope containing the role definition you want to delete,
and enter the Administration interface.
Warning
• Always ensure that each user has at least one role assigned other than the one planned for
deletion. After you delete a role definition, any users assigned only to that role lose access to all
content in the portal.
• If a user has at least one other role assigned, apart from the one deleted, they can retain access
to all content in the portal.
5. When you are ready to proceed, click Delete and confirm the action when prompted.
You can assign one or more roles to any user. A role definition must already exist in order for the role to be
assigned to users.
It is possible to assign a user multiple roles in a project, but this is not the recommended practice.
In particular, the roles project_admin and project_user should be used exclusively, adding only the
project_assignable role if the user should appear in the list of users in the Assignee field. In general,
assign a role that provides the user all the permissions needed to perform their tasks, and no more.
For example, the project_admin role provides all the permissions of the project_user role, so you do not
need to assign project_user in addition to project_admin.
Tip
You can easily review which permissions are granted by a role assignment. Select the role name on the
By Role tab in Administration User Management Permissions Management and
click Expand All.
Users must have the role of assignable, project_assignable or both to have Work Items assigned to
them.
If users report that they are missing in Assignee lists, an administrator should make sure such users are
assigned the Assignable role in the appropriate scope.
By default, permission to log on to the portal is granted to users having a role of user. If a user cannot log
on, review the assigned roles and make sure the repository-scope role user is assigned. When a new user
account is created, this role is not automatically assigned. You can tell if the user does not have this role if
the user account page shows [disabled] in red text. See Create User Accounts for more information.
The Everyone role is a synthetic role that all user accounts have. You can use it to assign general
permissions (incl. subversion access) that you want to grant or deny to all accounts. You cannot remove
the Everyone role.
Assign a Role
Procedure
1. Log on with administrator permissions for the scope in which you want to make role assignments,
and enter Administration.
2. Use the Open Project or Project Group dialog box to select Repository, or a Project.
The Roles page of Administration has Synchronize SVN Access File on the page toolbar. Synchronize
SVN Access File updates the access file of the Subversion repository, synchronizing it with the role
definitions and user role assignment configurations.
Note
Only the first part of the access file is affected, not the directory rules in the second part.
This function ensures that the access file contains a group for every user role and that the group
membership is in sync with the role assignment.
Generally, an administrator should only need to run this synchronization if people with an assigned role
cannot access repository resources as expected. (Access issues can be caused by externally editing the
access file, or manually changing the user-roles.xml configuration file in the repository.) Run Synchronize
SVN Access File once the manual file modifications are complete.
Related Topics
User Groups simplify the management of access rights and permissions. Administrators can create
personas or Groups with complex permission and role configurations, then easily assign a large number
of users to them. Users can be members of multiple Groups simultaneously, so administrators can
temporarily elevate a user's credentials by adding them to, for example, a Project-Admin Group. When
the task is done that required elevated credentials, the user can quickly be removed and reverted to their
previous access level.
Tip
Administrators on Linux can grant a user Group a basic level of Polarion administrative rights without
giving them system-wide privileges.
Tip
Looking to configure User groups with SSO?
Note
Only users with the Administration - Modify Configuration permission can access the
Groups administration page. They must also have Read/Write access to all Projects. We recommend
using the Global Polarion admin role to manage User Groups.
Assign users to a
Group automatically
on SSO logon
Edit or Delete a Remove users from Remove Global Remove Project
Group a Group Roles from a Group Roles from a Group
When you select a User Group from the table at the top, its details appear below.
(If you close the browser tab, move to another page on the same tab or click Cancel before you
Save, all changes will be lost.)
• Items marked for addition are highlighted in green.
• Items marked for deletion are highlighted in red.
Create a Group
Procedure
Caution
Do not name a Group using a name that is identical to one already used for a Global Role.
6. Click Save. (Or Cancel to exit without saving the new Group.)
The newly created Group appears in the table once the page is refreshed.
Procedure
a. Click Delete.
(This will delete Group's folder in the repository.)
b. Click Edit or just hover over and click on the Name or Description fields to edit them.
(You cannot edit a Group's ID.)
Procedure
Only users that can be added to the Group (and are not yet assigned to it), appear in the Add Users
dialog box.
(The maximum number of Users visible in the dialog box is configurable via a system property.)
4. Select one or more users.
Hover over a selection to view its ID. (A great way to distinguish between two users with the same
name.)
Tip
The Add Users dialog box supports multi-select.
Note
Highlighted items are only marked to be added or removed. (If you close the browser tab, move to
another page on the same tab or click Cancel before you Save, all changes will be lost.)
6. Click Save.
All changes to the Users, Global Roles and Project Roles columns are saved.
You can also assign Users to a User Group automatically by synchronizing them with LDAP, if you use it for
user authentication.
Each User Group can be linked with LDAP via an LDAP Search Filter.
• If LDAP Search Filter is blank, then the Group will not be synchronized with LDAP.
• If LDAP Search Filter is not empty, LDAP synchronization will attempt to update the Users of the Group
based on the LDAP query entered in this field.
Tip
See the Search filters and querying Nested Groups section for more information.
Polarion can be configured to synchronize the Group(s) a user is a member of each time they sign in via
SSO.
If SSO Synchronization Allowed is selected, the Group(s) they belong to in Polarion are synchronized
with the Group information sent by the configured SSO provider.
Tip
(See SSO Group synchronization - Getting started for more information.)
Procedure
Tip
These columns support multi-select.
5. Click Save.
All changes to the Users, Global Roles and Project Roles columns are saved.
Procedure
(The maximum number of Global Roles visible in the dialog box is configurable via a system
property.)
4. Select one or more Global Roles.
Tip
This dialog supports multi-select.
6. Click Save.
All changes to the Users, Global Roles and Project Roles columns are saved.
Procedure
Tip
This column supports multi-select.
5. Click Save.
All changes to the Users, Global Roles and Project Roles columns are saved.
Procedure
Procedure
(Only a limited number of users are displayed in the dialogue. This number can be configured by
administrators via a system property.)
3. Select one or more Project Roles.
Tip
This dialog supports multi-select.
5. Click Save.
All changes to the Users, Global Roles and Project Roles columns are saved.
Procedure
3. Select one or more Projects and/or Project Roles and click or Delete on the keyboard.
• This dialog supports multi-select.
• If a Project is marked for removal, its child Project Roles are too.
• If the last Project Role from a Project is marked for removal, then so is the Project.
(The baugi1 Project in the example above will also be marked for removal.)
4. Click Save.
All changes to the Users, Global Roles and Project Roles columns are saved.
◦ If there are multiple Users or Projects with the same Name, then these items are sorted by ID.
• The lists can be filtered using the field at the top. (It filters results as you type.)
• Filtering in the Project Roles column works for both Projects and Project Roles.
◦ A filtered Project is always displayed with all its child Project Roles.
Administrators can view the Role, User and Group information that's stored in the access file
at:
Tip
This can grant members of a User Group the ability to access SVN folders through an external tool.
Because Roles can be assigned to Users either directly or via a User Group, it is important to know where
it was done.
A Source column is visible in the Global Roles and Project Roles sections of the Users administration
page and when a Role is selected on the Roles administration page.
(Direct assignments are listed first and Groups following in alphabetical order.)
Note
Only direct assignments can be removed on the Users administration page. (Remove is disabled
for Roles assigned by Groups here.)
The Source column is also visible in the users list that appears below a Role when you click on it.
Once again, Remove is disabled for Users assigned by Groups here and must be removed via the
Groups administration page.
Permissions are an essential security issue. You should spend some time on this topic to ensure you
configure permissions securely and successfully.
• Global roles can be configured in the Repository scope and if assigned to users, they define their
permissions for the entire repository.
• Projects roles are configured for each project separately. When assigned to a user, they define the
permissions that the user has for that Project.
The combination of global and project roles assigned to a user defines the permissions they have and what
actions they can perform.
Warning
• You should configure roles BEFORE you configure permissions.
• Granting Polarion permissions does not automatically grant access to the files in the Subversion
repository.
• You must configure Subversion READ and WRITE permissions independently.
Make sure that Polarion permissions do not conflict wityh repository access permissions.
Tip
Administrators on Linux can grant users a basic level of Polarion administrative rights without giving
them system-wide privileges.
Manage permissions
Procedure
1. Log on with administrator permissions for the scope you want to configure ( Global or Project).
2. If you are not in Administration when you log on, enter the Administration interface. (
Administration in the tool view of Navigation.)
3. Select the scope ( Global or Project) that you want to configure permissions for. (See Access
Projects for more information.)
When reviewing and editing permissions, pay attention to the color scheme.
By Permission tab
• View the categories of Permissions, and access individual Permissions within each category. Categories
represent areas of the system for which access is controlled by permissions: projects, Documents, or
Work Items, for example.
• View all of the roles to which a selected Permission is granted.
• Grant or revoke the selected Permission from one or more roles.
The top half of the page presents a tree of Permissions, organized into categories. Expand the category
nodes to see the individual Permissions. For example, the Work Items category contains Permissions
applicable to Work Items — permission to view, permission to modify, etc.
When you select a Permission, the lower half of the page displays the Applicable Roles table. This table
lists the roles to which the selected Permission may be granted, and shows which roles have actually
been granted the selected Permission with a check mark icon in the Granted column. For example, if you
select Permission to READ under Work Items, you can quickly see which roles have been granted this
permission.
Procedure
By Role tab
The By Role page presents a tree of Permissions, organized into categories. Expand the category nodes
to see the individual Permissions. For example, the Work Items category contains Permissions applicable
to Work Items — permission to view, permission to modify, etc. The Permissions show the granted/not
granted status for the role currently selected in the Roles list. That list displays the roles configured for the
current scope (repository or project) in Administration: User Management: Roles.
Procedure
To grant additional Permissions to the selected role, simply select the check box next to any Permission
when the desired role is selected in Roles. To revoke a Permission, deselect the applicable check box.
You may sometimes need to control permissions explicitly for certain specific artifacts or some attribute
thereof, such as fields of Work Items. For example, a project might require explicit permissions control on
some specific Work Items or Documents, which is more restrictive than the general permissions for these
artifact types. You can accomplish this more granular level of permissions control with the per-dataset
permissions management feature, which enables you to create Custom Sets of permissions applied to an
explicit set of artifacts.
• Collections
• Documents
• Pages
• Plans
• Test Runs
• Work Items
A Custom Set is for one artifact type only. That is, you cannot have a Custom Set that controls permissions
for some Classic Wiki pages and some Documents. Each Custom Set controls permissions for a set of
artifacts that match a query, which you specify when creating the Custom Set. For example, suppose you
have permissions defined for Documents in general, but a project contains some Documents that are of a
type named Customer Requirements, and management wants more restricted access for that type than
for Documents in general. You can create a Custom Set containing a query that retrieves that type of
Documents as a set, and then define permissions for that set. Permissions applied to the set then override
the less restrictive permissions on Documents in general.
Tip
Limit READ restrictions to fields with values that do not change over time.
For example:
Let's say you create a Custom Set that restricts READ permissions for a Work Item with Internal as a
Category value.
If a Work Item has that value in the HEAD (latest) revision, users also won't be able to read earlier
revisions of the Work Item, even if they don't have Internal as a Category value.
When you create a Custom Set, it appears in the relevant artifact category when you expand it in
the permissions editor. For example, if you create a Custom Set for Documents named Customer
Requirements Documents, it will appear when you expand the Documents category in either of the tabs.
Another entry, Other Documents, is automatically created, which contains the preexisting permissions for
Documents.
Custom sets can be created both in the Global configuration and per Project. Global-level permissions,
together with its Custom Sets, are propagated to the Project scope if the Project does not have any
Project-scope permissions set. If a Project has at least one change in the permissions (compared to the
Global permissions), then newly created Custom Sets in the Global scope do not automatically propagate
to the Project.
If a Project inherits a globally-defined Custom set, then changes to it done in the Project scope never
propagate to the Global configuration. Instead, a Project-scope configuration is created and used.
If an artifact matches the query in more than one Custom Set in a given scope, then its permissions
are controlled by the first Custom Set in the permissions category for its artifact type. For example, if
a Document in the Documents category matches the query in Custom Set 1 and Custom Set 3, its
permissions are controlled by Custom Set 1.
When querying a Custom Set, it is possible to use query expanders — that is, query elements such as,
linkedWorkItems, PLAN, TEST_RECORDS that are decomposed to list of IDs in the background — in
queries. When using these, be sure that the user has the necessary permissions for all data accessed by
the query. It is also possible to use the variable $[user.id] in a Custom Set query. However, for simple
cases of assignee and author, it is recommended to use dynamic roles:
Warning
Query expanders consume more resources than general Lucene queries and should be avoided for
custom set queries. Use Lucene only queries instead.
Procedure
(Attachments are considered Work Item or Document content and are tightly tied to Description
permissions.)
You can now expand the new Custom Set and set permissions in the same way you set permissions for the
artifact type, as described earlier in this topic. Only items that match the query will be affected.
Warning
Query Tip You need to be sure the results of the query you enter include all the items that should have
their permissions regulated by the Custom Set. One way to ensure this is to go to the Work Items
topic in the project and use the Query Builder in the Table view to construct the query. You can browse
the results and fine-tune the query as needed. Once you are sure you have the correct set of artifacts,
you can click the drop-down icon on the Query Builder and select Convert to Text. You can then copy
the text of the query to your clipboard, and paste it to the Query field of your Custom Set.
You can also query for Document, Page, Plan, Test Run types and other attributes in permission Custom
Sets.
Let's say that you want to search for a Document so that you can assign permissions to it for external
users.
id:(DOCNAME1 OR DOCNAME2)
If you wanted to refine your search to a particular document type you'd use: type:[document type]
For Example:
type:generic
• attachments
• attachments.author.name
• attachments.author.id
• attachments.fileName
• author.id
• attachments.title
• author.name
• branchedFrom.id
• comments.text
• created
• derivedFrom.id
• derivedFrom.location
• id
• moduleLocation
• moduleName
• outlineNumbering
• project.id
• space.id
• status
• type
• updated
• updatedBy.id
• updatedBy.name
When you select a Custom Set, its properties are available in the lower pane of the Permissions
Management page. Here you can:
Administrators can configure the READ and MODIFY permission for most Work Item fields to grant or
deny read and/or modify permissions to different user roles. For example, if local laws prohibit employers
from revealing how much time an employee has worked to other employees, an administrator can deny
read permission for the Time Spent field to appropriate user roles.
Work Item field permissions are located in: Administration User Management
Permissions Management Work Items Fields.
As with other permissions, you can access the specific permission via a listing of the permissions (By
Permission tab) or by selection of a user role (By Role tab).
Caution
Note that denying permission to READ also denies permission to MODIFY. Keep in mind that denying
one or both these permissions may impact users' ability to perform such tasks as creating new Work
Items, reusing Work Items, and importing Work Items. More information follows in notes for specific
permissions.
When configuring Work Item field permissions, keep in mind the following points:
• If fields severity, priority and any other fields required for creating new Work Items are read-denied
due to the permissions configuration, then affected users cannot duplicate or move Work Items or reuse
Documents containing Work Items.
• For import/export and round-trip operations:
◦ The value of READ-denied Work Item fields are not shown in exported files when a user who is
denied the permission exports the item(s).
◦ If a user reimporting a round-trip document is denied READ permission for any field(s), the READ-
denied fields are ignored by the round-trip importer.
For a listing of Work Item fields that have permission to READ, see Fields With READ Permission.
You can set per-field permissions for the following fields of LiveDoc Documents:
You can set the Permission to READ, and Permission to MODIFY for Document fields. The MODIFY
permission for Documents is the parent permission for the field-specific permission.
Procedure
3. Select the By Permission tab, then expand Documents Other Documents Fields.
Results
The available Document field permissions appear under the Fields node.
It is important for administrators configuring permissions to understand several ramifications and potential
user impacts that may not be readily apparent.
The adding and resolving of comments on Test Runs are controlled by the two permissions: Permission
to COMMENT and Permission to RESOLVE COMMENTS. By default, users with a Reviewer, Pro, or
Requirements license can add and resolve comments on Test Runs, if their role allows it. If this is not
desired, you should explicitly deny these permissions for any roles that you do not wish to allow to have
them.
The comment permission is a child of Permission to MODIFY. If you grant that permission to some role
that does not currently have it, the Permission to COMMENT is granted as well unless you explicitly deny
it.
They can configure Polarion so that users can only see other users in the same Projects that they are in.
(They would only see the user ID of other Polarion users that they do not share a common Project
with.)
Tip
Even if you are not concerned about user privacy but have many Polarion users, you should consider
enabling this feature.
If you do, users who do not share a common Project are excluded from drop-down menus and
queries.
Your users will thank you for not having to scroll through long lists of users to find their teammates.
Procedure
2. If you are not in Administration when you log on, enter the Administration interface. (
Administration)
a. Select ( ) Peer to hide user information for users that do not share at least one common
Project.
Select ( ) User to allow all Polarion users to view all user information.
(Including information about users with whom they do not share at least one joint Project.)
8. Click Save.
Confirm your selection by checking the Granted column.
• In the example below, the viewing user has the Peer role granted for Permission to VIEW USERS
globally so they can only view user information for users that they share at least one Project with.
The MTest has left the Project and they no longer have any Projects in common.
You can also grant a specific user (who is not a global administrator) the ability to view all Polarion users in
the system.
Example
A high-level manager or Human Resource Director.
Procedure
2. If you are not in Administration when you log on, enter the Administration interface. (
Administration)
6. Click Create.
14. Click on the bottom section, scroll to Applicable Roles and select your new role.
Note
Setting user visibility also works when users view historical revisions.
Author
User
Updated By
Uploaded By
Comment By
Created By
Assignee
Approving User
Custom Field(s)
Attachment
Signed
Declined
Invited
Signed By
Plans Author
Assignee
Created By
Updated By
Custom Field(s)
Test Runs Author
Created By
Updated By
Custom Field(s)
Test Run Records Executed By
Custom Field(s)
Collections Author
Created By
Updated By
Custom Field(s)
Baselines Author
Custom Field(s)
Builds Author
Projects Lead
Spaces Author
Assignee
Updated By
Comment By
Space Owner
Lead
Comments
Work Records
Approvals
Approving User
Custom Field(s)
Jira Assignee
Author
Custom User
OSLC Assignee
Author
Custom Field(s)
Work Items Updated By
Created By
Author
Assignee
User
Name
Approvals
Approving User
Comments
Comment By
Work Record
Custom Field(s)
By default, if a Polarion user enters user?id=[User Name] at the end of a Polarion URL they are denied
access to other users' My Account pages.
You can configure Polarion so that users can view the My Account pages of other users with whom they
share at least one Project. (Peers)
Procedure
( Administration)
8. Scroll down to Administration in the By Permission tab and select Permission to MANAGE USERS.
10. Grant this permission to user, or a custom role if you defined one, and click Save.
11. Users can now view the My Account pages of their peers if they enter user?id=[User Name] in
the Polarion URL.
Polarion utilizes an integrated Subversion repository to manage all data artifacts. Access to Subversion is
controlled by the Subversion access file. Polarion provides a web based client with an interface to facilitate
administrators who need to control repository access directly in Subversion. Subversion administration and
access file management is a topic beyond the scope of this Help. Basic knowledge of the SVN access file is
assumed.
Note
Polarion does not officially support Improved path-based authorization implemented by SVN in
versions 1.10+.
Warning
Access control groups can contain other groups (as described in the above document), but only a single
level of nesting is supported.
The following example will work and the parent-group will effectively contain four users:
[groups]
grandchild-group = harry
Tip
Administrators on Linux can grant users a basic level of Polarion administrative rights without giving
them system-wide privileges.
The Access Management feature enables you to edit data in the SVN access file online, in either
repository scope or single project scope. It is an administration feature, so you must have administrator
permissions for the scope you want to work with.
Warning
If you create a Subspace within a Space, or move a Space/Subspace from another Space, the
new or moved Space does not inherit the Subversion repository restrictions or permissions from the new
parent. If you want to restrict access to a newly created or moved Subspace, you have to remove the SVN
access rights create a custom rule for permissions. See Configure user Permissions - Define permissions
for Artifact Sets.
Procedure
1. Log on with administrator permissions for the repository or project you want to work with, and open
it.
2. If you are not in Administration after logging on, click the Administration link in the Tool view
of Navigation.
Results
You can now browse the repository structure, and view and modify Role, Group and User assignments.
The Access Management page is divided into two parts, top and bottom. The top part enables you to
browse through the repository structure as it is defined in the access file, and review the current Role and
User assignments for folders and files. Keep in mind that this part is a viewport into the SVN access file, and
what you see is what is currently in that file.
The upper part of the page displays a string that shows the repository path to the currently selected folder
or file. Some or all of the folder names in the path are clickable depending on your permissions:
• If you have global ( Repository) administrator permissions, the all folder names in the path are
clickable enabling you to navigate all the way up to the repository root.
• If you have project administrator permissions, the full path to the project root folder is displayed, and
you cannot navigate higher than that folder.
The lower part of the Access Management page provides detailed information about access rights
currently defined for the folder or file selected in the top part of the page. In the lower part you can:
• Add, edit, or remove Role and Group assignments for the selected folder or file. Click the (Edit) icon in
the Roles and Groups Assignment section in the lower part of the Access Management page.
• Add, edit, or remove User assignments for the selected folder or file. Click the (Edit) icon in the Users
Assignment section in the lower pane of the Access Management page.
• Review Users, Roles and Groups that currently have read and write permission for folder or file currently
selected in the upper page division.
• Review Users, Roles and Groups that currently have read-only permission for the folder or file currently
selected in the upper page division.
By default, files in a folder have the same access permissions as the containing folder. If you want some
files to have different permissions, you can grant or revoke them on individual files.
For example, if you wanted to set access control on the Catalog Specification Document in the eLibrary
example project, you would set the desired permissions on the folder Default Repository/Demo Projects/
elibrary/modules/Specification/Catalog Specification/. When repository access management restricts a user
from accessing a Document, the Polarion user interface does not show the Document to the user in
Navigation. Users can still see links leading to restricted Documents in Pages, other Documents, Work
Items, and other content, but if they click such links they are shown a message informing them that access
is restricted.
You can edit Role and Group assignments in either global or Project scope. Access by Roles and Groups
Assignment is generally considered preferable to assigning access to individual users.
Tip
If you have global administrator permissions for the repository, but you are editing Role and Group
access in the Project scope, then the appearance of some items in the Roles and Groups
Assignment list is somewhat different than for administrators having just project-scope administrator
permissions. Global administrators see Roles prefixed with a project ID — myproject-project_user,
for example. A project administrator sees the same role rendered as project_user.
1. Open the repository or project you want to manage and navigate to User
Management Access Management.
2. In the top part of the Access Management page, browse to the repository folder or file for which
you want to edit Role assignments and select the item. The selected folder or file's SVN access details
appear in the lower pane.
3. In the Roles and Groups Assignment section, click (Edit). The table of currently assigned Roles
and Groups become editable. Each row of the table corresponds to a Role or Group and the
permissions currently assigned to them. The last row lets you specify a Role or Group and their
permissions to add to the currently selected folder or file. Columns correspond to user role and
permissions. Check boxes correspond to enabling (selected state) and disabling (deselected state)
each permission.
Tip
Deny All overrides the other permission settings and revokes all permissions for the selected folder
or file.
Procedure
1. Make sure you are editing the correct folder or file - select it in the top pane of the Access
Management page. If the Roles and Groups Assignment table is not editable, click the (Edit)
icon on the section header.
2. In the last row of the table, click the icon to add a new row. Select the Role or Group that you want
to add to the access file from the list in the Role or Group column. (For information see Configure
User Roles and Create a User Group. )
3. Select the check boxes corresponding to the permissions you wish to assign to the added Role or
Group. The options are:
• Read - Select to assign read-only permission, clear to revoke it.
• Read & Write - Select to assign read and write permission, clear to revoke it.
• Deny all - Select to deny all permissions, clear to revoke denial.
4. If you want to add another Role or Group and set their permissions, click the icon in the Actions
column to add another row to the table. Select the Role or Group and assign permissions as
described above.
5. Click Save in the lower pane's toolbar to save changes from the GUI to the SVN access file.
Procedure
1. Make sure you are editing the correct folder or file - select it in the top pane of the Access
Management page. If the Roles and Groups Assignment table is not editable, click the (Edit)
icon on the section header.
2. On the row(s) of the Role(s) or Group(s) you wish to remove, click the in the Actions column. The
row becomes highlighted. (If you make a mistake, click the Cancel button on the lower pane toolbar
and start over.)
3. Click Save in the lower pane's toolbar to save changes from the GUI to the SVN access file.
As previously mentioned, it is generally considered preferable to assign Subversion access by Role rather
than by User. The most common reason to edit User assignments is in situations where some clean-up of
the access file is desirable, removing User assignments that may have found their way into the file at some
time or another. Of course, if you wish to assign access to some specific Users, you can do so.
Procedure
1. Open the repository or project you want to manage and navigate to User Management
Access Management.
2. In the upper pane of the Access Management page, browse to the repository folder or file for which
you want to edit User assignments and select the folder. The selected folder's SVN access details
appear in the lower pane.
3. In the Users Assignment section header, click (Edit). The table of currently assigned Users
becomes editable. Each row of the table corresponds to a User and the permissions currently
assigned. The last row enabled you to specify a user and permissions to add to the currently selected
folder or file.
Procedure
1. Make sure you are editing the correct folder or file. Select it in the upper part of the Access
Management page. If the User Assignments table is not editable, click the (Edit) icon on the
section header.
2. On the row(s) of the User(s) for whom you wish to remove SVN access, click the icon n the Actions
column. The row becomes highlighted. (If you make a mistake, click the Cancel button on the lower
pane toolbar and start over.)
3. Click the Save button in the toolbar of the lower part to save your changes to the SVN access file.
Procedure
1. Make sure you are editing the correct folder or file. Select it in the upper pane of the Access
Management page. If the Users Assignments table is not editable, click (Edit) icon on the section
header.
2. In the last row of the table, in the Users column, select the User to which you want to assign
permissions. (For information about configuring Users, see Configure User Roles.)
3. Select the check boxes corresponding to the repository access permissions you wish to assign to the
selected User. The options are:
4. If you want to add another User and permissions to the table, click the icon in the Actions column
to add another row to the table. Select the User and assign permissions as described above.
5. Click the Save button in the lower pane's toolbar to save changes from the GUI to the SVN access file.
Warning
Do not deny any permissions to the polarion user. This is the user account of the Polarion system itself.
Subversion access management enables use of the tilde character (~) as an exclusion marker. Prefixing a
user name or role with this character causes Subversion to apply the access rule to users not matching the
rule. Polarion displays access rules as they are written in the access file, so prefixed items may appear in the
Polarion access management user interface if they exist in the access file.
You can find more information about this marker, along with some examples, in the Advanced
Access Control Features section of the web page at http://svnbook.red-bean.com/nightly/en/
svn.serverconfig.pathbasedauthz.html.
You can manage permissions for Spaces by user, role or group. You can define who can access or edit
them to the Subspace level. If you restrict READ access to a Space it's hidden from searches and menus for
anyone without access.
Tip
• See Permission precedence to understand what permissions take precedence over others.
• You can view existing Space Owners in the Space Owners column of the Space's Index table.
• If no permissions are granted via Manage Access to any Spaces, then permissions are taken from
Permissions Management.
• Project-level permissions are inherited from the default Repository (Global) level.
2. Scenario B: (Only READ on Spaces given through Permissions Management & Owner access
granted on S2).
S1, along with its artifacts, can only be read.
For S2 and S3, Owners are granted Owner privileges. (S3 inherits S2's permissions.)
Note
The permission.xml file is only created for the S2 Space at the following location in the repository:
Repository/ProjectName/.polarion/pages/spaces/S2/permissions.xml
(Even though S3 inherits all permissions from S2, a permissions.xml file is not generated for S3 unless
you grant an access level to S3 to an entity.)
Permission precedence
1. User Space permissions take precedence over role and group permissions.
(When a Space gets rendered, Polarion checks if the current user is an administrator. If yes, all
Space permissions are ignored, and access is granted.)
(If the current user is NOT an administrator, Polarion checks if they have explicit permissions and
grants/denies their access accordingly.)
If Polarion finds no Project role permissions, it checks and implements Global role and
group permissions. If there are conflicts ( Global roles deny access to a Space, but the group
permissions grant it) Polarion goes with the granted group permission.
5. Grant takes precedence over deny for groups.
If Polarion does not find explicit Project or Global permissions for roles or groups, then it
checks the access level of the parent Space and grants access based on the permissions it finds.
6. Grant takes precedence over deny between Global roles and groups
If a parent Space does not exist or its access is undefined, Polarion uses Project permissions
defined under Permissions Management.
Grant Space permissions via Permissions Management when you want to grant/revoke permissions to/
from different roles on initial (top-tier) Spaces.
Tip
Not sure how permission inheritance works when you set permissions via Permissions
Management and Manage Access?
Note
• Permissions for Spaces can only be granted or revoked for Roles under Permissions
Management.
• If you want to define Space permissions by users or groups, use Manage Access.
• READ
Users can only view a Space and the artifacts within it. ( LiveDocs, Live Reports, Info
Pages, or Classic Wiki Pages).
To view the artifacts within a particular Space, you must grant READ permission for both the
artifacts and the Space.
Caution
Revoking the READ permission on a Space hides it (and the artifacts it contains) from:
◦ The Navigation panel.
◦ Search results when searching for Spaces or Documents.
• CREATE NEW
◦ Users can create new Spaces. (Grants READ and MODIFY permissions for Spaces).
◦ Users must have the CREATE NEW permission for the Space AND an artifact type to create one
within the Space.
• MANAGE
Project Level:
• project_user/user: Only READ permission for Spaces.
• project_approver: READ and MODIFY permissions for Spaces.
• project_assignable: READ, CREATE NEW, and MODIFY permissions for Spaces.
• project_admin: All permissions for all Spaces.
Global Level
• user: Only READ permission for all Spaces.
The Manage Access option lets administrators and the owners of a Space control access for a single
Space without using Permissions Management. You can configure permissions for users, roles, or groups
under Manage Access right down to the Subspace level.
Tip
Not sure how permission inheritance works when you set permissions via Manage Access and
Permissions Management?
Example
A user can be the owner of a Logistics Space, but can only view (READ) a Human Resources Space.
Procedure
1. Click on the Index page or Home page of a Space and select Manage Access.
( Manage Access is only visible to administrators and the owners of a selected Space.)
Tip
• Search for a target using their ID, Name, or E-Mail. (If present.)
• Click the field and hit the Spacebar to list all available options.
• Results do not include the admin role (they already have all permissions enabled) or the current
user.
4. (Optional) Owners and administrators can search for entities under Grant Access to, can use to
grant Space permissions to the Space, and can use to revoke existing permissions.
Tip
A user that creates a Space is considered its Author and is assigned the Owner role.
(Other Owners and administrators can remove the Author's Owner permission.)
Note
If an entity (User/Group/Role) does not have WRITE access to the SVN repository (Administration
> User Management > Access Management), but that entity has explicit Can Edit/Owner access,
then that entity will not be able to modify the Space or perform any operations which these access
levels provide, since the repository WRITE access was not given for that entity.
Therefore, make sure that the entity has repository WRITE access before assigning explicit Can
Edit/Owner access to them.
You must enable the following permissions before users can add comments to Pages:
Tip
You can also set up email notifications for page comments
• COMMENT: Users can add new Page comments (including the initial root comment) or reply to a
specific comment.
(They must also have the READ permission.)
• RESOLVE: Users can resolve and reopen Page comments.
(They must also have the READ permission.)
Project roles:
• project_user: No comment related permissions.
• project_approver: READ, COMMENT, RESOLVE
• project_assignable: READ, COMMENT, RESOLVE, MANAGE
• project_admin: READ, COMMENT, RESOLVE, MANAGE
Global roles:
• user: No comment related permissions.
Tip
See Configure user permissions for more information.
You can configure notifications so that targeted users are emailed when a change is made to the Page.
• rich-page-updated:
Email notifications get sent every time a Page is updated.
Available targets:
current-author, current-user, global-role, project-lead, project-members,
project-role, single-email, single-user
• rich-page-commented:
Email notifications get sent if any comment is added.
(Also triggers a rich-page-updated notification.)
Available targets:
all-commenters, comment-thread-participant, current-author, current-user,
global-role, project-lead, project-members, project-role, single-email,
single-user
• rich-page-comment-removed:
Email notifications get sent when any comment is removed.
(Removing any comment also triggers a rich-page-updated notification.)
Available targets:
all-commenters, comment-thread-participant, current-author, current-user,
global-role, project-lead, project-members, project-role, single-email,
single-user
Note
See Notification targets if you do not know what an available target is.
3. Select one or more of the following in the rich-page notification configurations you want to edit.
a. Select include in the first drop-down, the notification target in the second drop-down and click
(The target is notified when the rich-page event occurs.)
b. Select exclude in the first drop-down, a target to exclude in the second drop-down and click
(The target is NOT notified when the rich-page event occurs.)
c. Click beside an existing notification to remove it.
4. Click Save at the top of the page when you are done.
Users may regularly split their working time between two or more projects (sometimes called time
sharing). Administrators can configure such time splits for individual users. The time-split data is accessible
to report widgets and scripts, and internal system calculations. This topic explains how to configure user
time splitting between projects.
Procedure
1. While in the Administration interface, select Repository, or any project in the Open Project or
Project Group dialog box.
2. In Navigation, expand User Management and select Users. The table of users for the selection
appears in the top pane of the Users page.
3. Scroll or use Search to locate the user whose time is to be split between projects, and select the
relevant row in the table in the top part of the page. The user's details appear in the lower part of the
page.
In the table, the Time-split Assignments column displays the current split time assignments, if any,
for the selected user.
4. Scroll down, if necessary, and locate the Time-split Assignments section. The section This is where
you assign the percentage of the user's time for each project.
5. Click the section header to edit the data in the section.
Each row in the Time-split Assignments section lists a project for which the currently selected user has
Work Items assigned. (You cannot split a user's work time into a project for which the user has no assigned
Work Items.) You use the % of Total Time column to assign of percentage of the user's total working time
to two or more projects.
Warning
The values you enter in % of Total Time must be integer values (and you do not need to enter the %
sign). For example: 25 is a valid entry, while 33.3 is invalid and results in an error message when you
save changes.
It is not possible to save the configuration if the sum of all time-split assignments is more than 100.
The configuration splits the user's total working time between the different projects. That time is a
combination of the Global Working Calendar configuration and the selected user's Personal Working
Calendar configuration.
Some features need to have a user name and a password specified in the configuration in order for the
feature to work properly. For example, a scheduled job that imports automated test results needs the
credentials of the user it creates the Test Cases and Test Runs for. For security reasons, administrators
may not want certain user credentials stored in the underlying configuration file in the file system.
The User Account Vault provides a secure way to store user credentials, and enables administrators to
reference them in a secure way in configurations. For each user account that needs to have its credentials
specified in configurations, you create a Key and associate a user name and password with it. Then in
configurations, instead of supplying the concrete user name and password, you supply the Key value from
the User Account Vault. Polarion automatically resolves Key references when necessary.
Note
You cannot edit an existing Key. If you want to change its password, you must Delete it, then Add
it again with the new password.
The User Account Vault can be configured in the global (Repository) scope only.
Procedure
• Add a key:
Enter a Key name, a User Name, a Password, re-enter the Password, then click .
• Remove a key:
Click to the right of the key that you want to remove.
Caution
Before deleting a Key, make sure it is not used in any configuration, especially in scheduled
jobs, or the jobs will fail when they are run.
5. Click Save.
Tip
Do not create Keys as credentials for people who use Polarion. Keys should refer to special user accounts
created for automated data access. For example, there is a system user named polarion. This user needs
to be specified for jobs like the one cited above for test result imports. You should create a Key for this
user in the vault and specify that Key in all configurations requiring system user credentials, rather than
the actual user name and password.
To be able to create new projects, you must be granted that permission by an administrator. There are two
basic scenarios for creating a project:
• Create a completely new project from a Project Template. This creates a new folder in the repository as
the project root.
• Mark an existing repository folder as a project. In this way you can begin managing existing sources and
other content with Polarion. This option requires permission to access global Administration.
Procedures for this are covered in the topic Create a New Project From a Template.
Tip
If you are in Administration, open Repository, then in Navigation select Projects, and use the
New Project button on the Projects page of Administration to launch the New Project dialog box. The
rest of the process is the same as described in the User Guide.
Related Topics
If you have an existing folder structure in your Subversion repository that you want to start managing with
Polarion, you can do so by specifying the root folder and telling Polarion to mark it as a Polarion project.
Procedure
1. Log on to Polarion and click the Administration link in the tool view of Navigation. You must have
global administrator permissions to access Administration.
4. Click the Mark Project located on the toolbar above the table of projects.
The new project wizard appears titled Mark existing location as Project.
Warning
• If you're re-marking an existing project, don't change the Project ID or you'll lose its History.
• You can't use special characters (/\©:*?"˂˃|;ˋ~'# etc.) in the Location field.
Tip
You can also upload and use your own custom project icon.
In the Administration interface, you can easily access a table listing all the Projects in Polarion's Subversion
repository. You can select any Project in this table to see its properties, and you can modify those
properties for which modification is allowed.
Procedure
1. Click beside the project (or Project Group) in the Navigation Header and select Repository.
Note
You cannot modify the ID or Location fields.
• Name
The name of the project that appears to all users in the Open Project or Project Group dialog box.
• ID
The project's ID. Read-only.
• Lead
Name of the project leader. Default value for a new project is the current user, who is creating
the project. You can select a different name from a list of users. If the user you want to specify is
not listed, possibly the person does not have a Polarion user account, or their account does not
have the necessary permissions. You can safely skip this and specify a project leader later on in the
project Administration interface.
• Active
Flags whether or not this project is actively under development. Default for a new project is the
selected state (true). If the new project will only be active later on, you can deselect this option and
enable it later on in the project Administration interface.
• Start
The date on which work will begin, or work began, if you have marked an existing code base as
a Polarion project. Default value for a new project is the current date. Click the calendar icon to
pick a date. If not known, it is safe to skip and specify a date later on in the project Administration
interface.
• Finish
The date on which the project is scheduled to finish. Click the calendar icon to pick a date. If not
known, it is safe to skip and specify a date later on in the project Administration interface.
• Location
The location of the project's root in the repository. Read-only.
• Icon
An icon for the project that appears in the Navigation Header.
◦ Projects created before Polarion 22 R2, projects created without a template, are assigned the
default project icon and a transparent background.
◦ You cannot use custom project icon and color settings for Project Groups and default
Repositories. The following are used:
• Color
The background for the project that appears in the Navigation Header.
• Description
Enter free-form text describing the project. This can be helpful to new team members, managers,
and other stakeholders.
6. Click Save.
If you want to use a custom project icon, you must configure it via the Repository Browser.
3. Click Repositories.
4. Click Navigate to Repository Browser >>.
5. Click on the top right until you are in the .polarion folder.
6. Click on the icons folder. If you do not see an icons folder create one.
Note
Polarion is case-sensitive, so ensure your path case matches the repository path in Step 6.
Optional alternatives:
a. Enter a relative path to your custom icon if it is located on the same computer that's serving
Polarion.
b. Enter an absolute path if it located on a different server.
c. Polarion's Apache public folder can also be used: Polarion\bundled\apache\htdocs\
[your_icon.svg].
17. Save your changes.
Your custom icon should now appear beside the project's name in the Navigation Header.
Users with the appropriate permissions can move or remove an existing Project .
You can have projects in your repository that are not currently managed by Polarion: projects not currently
under active development, for example. Removing such projects from management by Polarion does
not remove any artifacts from the repository. If you want to restore a removed project (if development
resumes, for example), you can do so.
Move a Project
There may be time when you want to move the location of a Project within the repository. For
example, the project might be finished, and you want to archive it and keep it out of the list of projects still
in progress.
Polarion provides the possibility to move projects to another location in the repository. Moving preserves
the project history.
Tip
If you want to move an existing Project to a new Project Group, you can create the Project
Group on the fly while moving the Project just by adding its name in the path.
(You cannot create an empty Project Group, then fill it with Projects.)
There are a couple of caveats to keep in mind when moving projects for any reason:
(You'll have to create a folder for the Project if you're moving it to a Project Group that already
contains Projects.)
• Future new projects cannot reuse the Project ID of any previously existing project in the repository, even
if the location has been unmarked as a project.
Procedure
2. In the Open Project or Project Group dialog box, select the Repository node. (See: Access
Projects.)
(A new Project Group is created automatically if you add its name followed by / before the
Project ID in the Location field.)
Caution
You cannot have two projects in the same folder.
Remove a Project
Procedure
2. In the Open Project or Project Group dialog box, select the Repository node. (See: Access
Projects.)
a. Click Unmark and OK to confirm to stop Project from appearing in the portal.
(Its files will remain in the repository.)
b. Click Delete and OK to confirm to remove the Project from the portal and delete its files
from the repository.
Tip
• If you create a project from a template with icon and color settings, it inherits these settings.
If no icon/color settings are defined, they are assigned the following by default.
Like other kinds of templates you are familiar with, Project Templates save significant time when creating
projects that are fundamentally the same or very similar. A template makes sense whenever it is beneficial
to have some predefined configurations and/or content that can be reused for multiple new projects. For
example, you might create a Project Template to be used for all new projects created for a specific team in
which all project users and user roles are already defined in the template. Or you might create projects that
already contain base requirements provided by the Project Template. The main idea is to eliminate, or at
least minimize the need to tweak the project configuration in new projects.
A Project Template can contain any project-scope settings and content that a project can contain. Here are
some common things it can make sense to include:
Note
Legacy Project Templates: Prior to version 3.3.0 of the Polarion platform, default Project Templates
shipped with Polarion were located on repository path /.polarion/projects/templates/, and
all subdirectories in this location were considered as individual Project Templates. As of version 3.3.0,
Polarion Project Templates are part of the binary distribution as plugins. Any custom Project Templates
you may have created in prior versions remain in the repository in the same location and users can
still instantiate projects based on them. If you want to create new Project Templates based on these,
however, it is recommended to port them to the newer template implementation.
Procedure
1. Download an existing Project Template, locally edit downloaded configuration and content files
using appropriate applications, and then upload a Zip archive of the modified template to the
Polarion portal. Recommended only for advanced administrators or developers who know Polarion
thoroughly, and are able to work with XML code.
2. Develop a template model project in Polarion. Create a project from an existing Project Template
in a sandbox area on your portal and modify it as desired. Then export the modified project from
the repository, package the necessary files and folders into a Zip archive, and upload the archive to
the Project Templates page on the portal. This option is recommended if you are new to customizing
Project Templates. See the linked section for details. Recommended for most template developers.
Anyone can work on developing custom Project Templates using the approaches outlined in this topic, but
only Polarion administrators with global permissions can upload or download templates to and from the
Polarion portal. ( Administration Global Administration Project Templates)
• View Project Templates. The page includes any custom Project Templates that have been developed and
uploaded. You can select All to see all available templates, or filter the view to show only Polarion
Templates, or only Custom Templates.
• View the properties of any Project Template. Properties include the ID, name, description, and license
type required for use.
• Create a duplicate of any Project Template listed on the page.
• Download a selected Project Template to your local system for customization.
• Upload a customized Project Template to the portal.
• Update an existing Project Template with a new, locally developed version.
• Find Project Template extensions. Access a hyperlink that leads to the Project Templates page of the
Polarion Extensions portal.
You can view the properties of any template appearing in the Project Templates administration page. This
is useful if you are planning to create custom templates because each Project Template in the system must
have a unique ID. By viewing properties of existing Project Templates, you can ensure that you do not give
any custom Project Template a duplicate ID.
You can easily create a duplicate of any existing Project Template. This is the recommended approach for
creating a customized version of an existing template by downloading the duplicate, customizing it locally,
and replacing the duplicate with the customized version. Best practice is to keep all the default templates
shown in Polarion Templates and customize only copies created by duplication.
Procedure
Immediately after duplication, the duplicate Project Template appears in the New Project dialog box. It can
be used by any user who has project creation permissions to instantiate new projects from it. Of course, it
provides exactly the same configuration and content as the original template until it has been customized
and the custom version uploaded to the Project Templates page. Assuming you are creating a duplicate
Project Template in order to customize it, you should make sure all users know not to use the duplicate
Project Template until customization is complete.
Procedure
You can use any of the Project Templates shipped with Polarion, or available on the Polarion Extensions
portal, as the basis for custom Project Templates.
Tip
To familiarize yourself with what each of the default templates provides in terms of configuration,
Documents, Pages, etc. create a Sandbox project from each of the Project Templates listed in the Create
New Project wizard and explore them. You can delete these projects later on once you know about
them.
When you decide which of your existing Project Templates you want as the basis for a custom Project
Template, you have three options:
Procedure
1. Download an existing Project Template, customize the downloaded template files locally, and
upload the modified template, overwriting the original.
2. Create a duplicate of a Project Template, download and customize the duplicate locally, and upload
the modified duplicate.
3. Create a Sandbox project from the project template you want to customize, work on that project in
Polarion to customize the configuration and content, export the modified project from the repository,
and upload it to the Project Templates page in Global Administration.
Note
If your custom Project Template is large, you may find that you cannot upload it due to the attachment
size limit currently set in the system configuration. In such cases, your Polarion administrator can
temporarily increase the limit set in the maxAttachmentSize system property.
You can potentially use some existing project as the basis for a Project Template. If you do that, the project
should not be referencing any specific revisions (baselines, frozen Work Items or Test Runs, for example)
unless you are sure that the template will always be used with the same repository. Such references
can cause problems if the template is used on a different repository. Best practice is to avoid creating a
template from a project that contains specific revision references.
Note
This option is for advanced users who are experienced with Project Template structure, content, and
customization. Ability to read and write XML is necessary, and familiarity with Java-style properties files
is helpful. After downloading a Project Template, you can implement customizations by editing various
files on your local system. You will need a text editor application at a minimum. An editor or IDE for
HTML and XML is recommended. An editor that recognizes syntax of Java properties files is also helpful if
you will create a template properties file.
With this approach, you download an existing Project Template (default or duplicate), modify existing
configuration and content files locally, create any new files needed for the template, and upload a new
version of the template to your Polarion portal using the same file name to overwrite the existing template,
or a new file name to create a new custom template.
Caution
Overwriting the default Project Templates that come with Polarion is not recommended, as someone
might want to use one as the basis for a custom template. Best practice is to create a duplicate of any
default template, with a different ID and name, which you can then customize and overwrite.
Procedure
1. Download a copy of the Project Template you want to customize from the Project Templates
administration page and unpack the archive.
2. Edit the XML files in the local copy of the Project Template, creating new XML files — for new
Documents, Pages, etc. as needed.
With this approach, you develop a model project online in a sandbox area on your Polarion portal so that
it has all the features and content you want to deliver in a custom project template. You can either create
this model project from an existing template (usually the more efficient approach), or as an empty project
in which you develop everything for the configuration and default content. When your model project is
complete, you then download folders from the repository, package them locally into a Zip archive, and
upload the packaged template to the Project Templates page in global Administration.
Procedure
1. In the Polarion portal, instantiate a sandbox project based on the Project Template you want to
customize.
2. Then proceed to customize that project in the portal, modifying configurations and creating
Documents, Pages, and other artifacts as needed.
3. Use the Repository Browser to save the project folders containing modified configuration and content
files to some location on your local system. The folders that must always be packaged in a Project
Template are: .polarion, _wiki, and modules. However, depending on the purpose of the
project, you may need to deploy other folders. For example, if there is source code in your model
project, and you want it in projects instantiated from your template, you need trunk. If source code
has been updated via repository commits, the branches and tags folders may be needed.
4. Create an empty folder to hold all the content of your template. The name of this folder will
constitute the template ID in Polarion, so be sure it contains only characters that are valid for IDs
in Polarion.
For example, if your template is for a project to gather software requirements, and you name the
folder software_reqts_template, that string will be the template ID when you upload the template
to Polarion.
Tip
The main thing to keep in mind is to avoid spaces in the name. Use underscores to separate words
to avoid any problem with word separation.
5. Move or copy all the files and folders you want to deploy in your template into the new folder. If you
have a template.properties file, be sure to move or copy it to the new folder also.
6. Create a Zip archive of the folder you created to contain your template files and folders. Give the
archive a file the same name as that folder. For example, if the template content folder name is
software_reqts_template, the Zip archive must be named software_reqts_template.zip.
7. Upload the Zip archive containing your custom project template files to your Polarion portal using the
Upload button on the Project Templates administration page.
The new template appears in the Custom Templates section of the page.
After modifying the template in one of the ways described earlier, upload a Zip archive of the modified
template in Global Administration → Project Templates. The Zip file must have the same file name as the
existing template's ID. That causes Polarion to overwrite the existing template. You can check the existing
template ID by clicking the Properties button.
Caution
• When you overwrite an existing Project Template, the previous version is no longer accessible in the
portal. It still exists in earlier revisions in the repository, but requires a Subversion administrator using
an external client to gain access to it.
• Uploading an updated version of a project template has no effect on existing projects that were
created based on a previous version of the template. For example, if your updated template contains
revised workflow for some Work Item or Document, the changes do not propagate to any existing
projects created from the older template version. If you want such projects to have the revised
workflow, you must modify the workflow manually in each one.
There may be cases where you want your custom Project Template to provide some predefined Work Items
in the projects instantiated from it. If so, it is easier if you develop your template as a project in Polarion,
and create a Project Template from that. When you create your template development project in Polarion,
you specify a prefix for new Work Items. For example, you might specify MYTMPL, in which case new Work
Items in your template project will have IDs like MYTMPL-100, MYTMPL-101, and so on.
When your Project Template is finished and deployed, and when users create a project based on your
template, they will be able to specify a prefix for new Work Items in their new project. For example,
suppose the project creator specifies FSPECS as the Work Item prefix for a project based on your Project
Template. New Work Items created by project users will have IDs like FSPECS-100, but any predefined
Work Items provided by your Project Template will not have this prefix. Rather, they will retain the original
MYTMPL prefix. You need to make sure to replace your Work Item prefix with the user-specified prefix in
user-created projects. Because not all Project Templates need to provide default Work Items, this prefix
replacement is not enabled by default in custom templates.
To have Polarion replace the Work Item Prefix from template-provided Work Items, add the following lines
to the custom template's template.properties file file:
trackerPrefixToReplace=PREFIX
process=.polarion/tracker/fields/workitem-type-enum.xml
In the example above, 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.
Note
These lines are present in the default templates that ship with Polarion.
You can optionally create and configure a file named access.template which, when created in the root
folder of a Project Template, controls low-level access permissions for new projects instantiated on the
Project Template. Rather than being copied into the instantiated project, the file content is inserted into the
Subversion access file, assuming one is configured and accessible, which it normally is.
[groups]
{$project_id}-project_admin = {$current_user}
{$project_id}-project_user =
[{$project_location}]
* =
@admin = rw
polarion = r
@{$project_id}-project_admin = rw
@{$project_id}-project_user = r
[{$project_location}/.polarion]
@{$project_id}-project_admin = rw
@{$project_id}-project_user = r
[{$project_location}/.polarion/tracker/workitems]
@{$project_id}-project_admin = rw
Pay particular attention to the references to user roles such as project_admin and project_user.
The role identifiers in the above example are defaults in some Project Templates delivered with Polarion.
If custom roles have been configured in your the Project Template, you should reference the identifiers of
those roles when configuring the access.template file.
Be aware that if no access.template is defined in a Project Template, Polarion will add the content of
the default access.template to the access file when a new project is instantiated from the template.
You can specify project template properties for the custom Project Templates you create in a file named
template.properties. Use of this file is not required, but is recommended. The file must be placed in the
root folder of your Project Template.
The internal data structure must be standard Java properties file syntax, containing key=value pairs
(see the example at the end of this topic). Java-style comments are allowed. The following properties are
recognized:
• project-id
• project-name
• tracker-prefix
• trackerPrefixToReplace
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 a ; (semicolon). Names cannot start with
a / (forward slash)
param.PARAM_ID.name Human readable names of parameters defined in the parameters property
process=.polarion/polarion-project.xml;.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 new
project creation process (except those listed in the 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 a newly created project.
You can use custom icons in the various configurations that use icons (Work Item Types, for example).
However, using custom icons will require some editing of the local copies of all XML configuration files in
which you have used custom icons, even if you developed the template online as a Polarion project. The
procedure below assumes that development method.
Procedure
1. Configure custom icons online in the desired Administration topics in the template model project,
noting which icons you used in which topics. (This will make things easier later.)
2. Export the template model project to your local system as described in Develop a template model
project using Polarion.
3. In the local copy of the exported template model project, use a text or XML editor to open the XML
configuration file for each configuration option where a custom icon is used. These will be located in
one or more subfolders under the .polarion/tracker folder. For example, if custom icons are used in
custom Work Item type definitions, edit .polarion/tracker/fields/workitem-type-enum.xml.
4. Check each <option> element looking for those in which the iconURL attribute is for a custom icon.
In those attributes, replace the name of the template project with %project-id%.
For example, if your configuration file contains the following:
Caution
If the iconURL attribute contains iconURL="/polarion/icons/default/enums/, do not
change it. That is the path to Polarion's default icon set, and it means the option is configured
to use one of those icons and not a custom icon.
5. Add the path and file name of each modified file to the process property of the template.properties
file. Separate each file spec with a semi-colon. For example:
process=.polarion/polarion-project.xml;.polarion/tracker/fields/
customType-severity-enum.xml;.polarion/tracker/fields/customType-status-
enum.xml;
Over time you may find that some custom Project Templates are obsolete and should be deleted. It is not
possible to delete such templates on the Project Templates page of Administration. You need to use the
Repository Browser to locate the template in the repository and delete it.
Procedure
Results
If you now open the Project Templates page in Global Administration, the deleted template(s) no longer
appear in the Custom Templates section.
in addition to the integrated Subversion repository, Polarion supports revision linking with external
repositories in several popular version control solutions to enable traceability into externally maintained
code bases. If you have existing repositories that you want to use with your Polarion installation, you need
to configure your portal and/or projects to work with them. You can do this in the Repositories topic of
Administration in the global repository or project-specific scope.
For general information, currently supported external solutions, and configuration procedures, see
Configure External Repositories.
Work Items are a major focal point of data and activity managed by Polarion. There is no single definition
or configuration of Work Items that is applicable to all needs everywhere, so Polarion provides extensive
possibilities to customize Work Items and functionality related to Work Items.
The Work Items topic of the Administration interface provides access to all configuration options
and setting for Work Items.
Tip
If you are just beginning with Polarion administration, you might find it useful to familiarize yourself
with basic concepts and other information about Work Items in the User Guide.
Work Items represent artifacts like Requirements, Tasks, or Change Requests. You can define
Work Item types in the global configuration, the project configuration, or both.
For projects, the default types are predefined in the project template the project is based on. If the default
types do not meet your needs, you can create your own.
• Defect is a default Work Item type but your organization calls them Bugs or Features.
(You can tailor the name, icon and custom fields of an existing type to your needs.)
• A project needs to track supplier parts, but there's no equivalent Work Item in the default configuration.
(You can create a Supplier Parts artifact and use it in other projects by creating or customizing a
project template.)
Procedure
1. Log on with administrator permissions for the scope you want to configure (Global or project).
2. If configuring a project, open the project. Otherwise, open the Repository.
Note
Must be all letters and numbers and be written as a single word.
6. Enter the name of the Work Item that users see in the Name field.
7. In the Icon column, click Select and choose an icon for the new Work Item.
• Click Choose File, select your own icon from your computer, and click Upload Project Icon.
• Scroll down and click on an existing icon from Polarion's icon library.
8. (Optional) In the Color column, enter a hex value (for example, #000000 for black). It can be used in
custom reporting.
9. (Optional) If you want your new Work Item Type to appear first when users add Work Items to
Documents, select Default.
10. (Optional) If you want the Work Item to contain the same fields as an existing Work Item, enter its ID
in the Template field.
Note
See Define Template Work Items for details.
11. Enter a Description that describes what the new Work Item is used for.
12. (Optional) Click and hold before ID and drag the Work Item to where you want it to appear in
13. (Optional) You can create custom enumeration pairs with a value dependency between them. When
used as the type for a pair of custom fields, the selection of a value on one enumerated list causes
some filtering of the values in another, limiting the choice of values for your users.
Tip
See Dependent Enumerations for details.
14. (Optional) Click to add another line for a new Work Item type or to remove an existing type.
15. Click Save on the top left when you are done adding Work Item types.
The configuration is stored in the workitem-type-enum.xml file.
Caution
Headings are used to structure Documents.
You should know their characteristics and limitations before modifying their configuration.
Polarion is preconfigured with a special Work Item type named Heading, whose main purpose is
structuring LiveDoc documents (Documents). This type provides Documents with a similar look and feel
to a word processing application. This topic describes the special characteristics, additional configurations,
and limitations applicable to the Heading type.
Characteristics
• Heading type Work Items are automatically created when a user formats Document content as Title,
or any heading level (Heading 1, Heading 2, etc.) to structure the content into hierarchical sections, as
is normally done in a word processing application. The structure of Heading items is reflected in the
Tree view of Work Items.
• Any normal Work Items within a section starting with a Heading are automatically linked to it with the
Document's structural Link Role (specified when the Document was created). Any lower-level Heading
occurring in the section is also linked with the same Link Role. The linking ensures that the structural
hierarchy of the Document can be displayed in other views, especially the Tree view.
• Heading type Work Items should not be created outside of the context of a LiveDoc document.
• The Heading type is designed as a lightweight Work Item. The type is implicitly added to project
configurations, even though it does not appear in the Types configuration. By default, Heading items
only contain very basic data - essentially just the Title, Outline number, and links.
• Unlike other Work Item types, the permission to create, modify, and delete Heading items is controlled
by the Permission to MODIFY LiveDoc Content, not by the Permission to CREATE, Permission to
MODIFY, and Permission to DELETE permissions of Work Items.
It is possible to "unlock" additional configuration of the Heading type (defining custom fields, form layout,
or modified workflow) by explicitly defining the Heading type in the project configuration (in Work
Items > Types).
Caution
Be mindful about the limitations of the Heading type. Due to the special nature of the type, some views
treat this type differently from other ("normal") Work Items. See the next section for more information.
Limitations
Heading items are important structure objects for Documents and therefore they are treated differently
from "normal" Work Items in several features, and various views that display Document structure.
• The Work Item Compare view of Documents uses Headings to outline the structure of the Document,
so no details other than Heading outline number or Title are displayed in that view.
• The Work Item Merge view of Documents uses Headings to outline the structure of the Document.
Merging of Headings or whole sections is not supported.
• Heading type Work Items in one Document cannot be referenced in other Documents. Branched
Documents always create new copies of Heading type Work Items, while normal Work Items are
referenced from the master Document.
• Filtering a Document does not filter out Headings from the Document content. Only the normal Work
Items are filtered by the query.
• Headings cannot be moved in the Document structure via Move Work Item in the Document structure
dialog box. They can be moved by cut-and-paste in the Document Editor.
• Branches created by Variants generation always copy the full Document structure, so even Headings
without any normal child Work Items are created in the Variant branch.
• Heading items cannot have an outline number prefix.
• Caution
Users should never attempt to convert a Heading type Work Item into a "normal" type by changing
the Work Item type (using Work Item Editor > Actions > Change Type to).
A Time Point is essentially a named milestone that has a date defining when it occurs. Project managers
can use Time Points to plan projects if they find that the Plans feature is not suitable, or more complex
than the project requires. Time points are shown in the Road Map view of Work Items.
For example, you might have a Time Point named Beta 1 that falls on some date prior to the actual end
date of the project. Work Items can be associated with a Time Point so that the developers can quickly
understand where a Work Item fits in the larger time picture, and managers can query to see, for example,
how many Work Items of what severity fall into a specific Time Point.
Time Points can be configured globally for the Repository, for project groups, and individual projects.
Procedure
1. Log on with administrator permissions for the scope you want to configure.
2. Enter Administration.
3. Open the project or repository in which you want to configure Time Points. (See Access Projects).
4. In the Navigation panel, expand the Work Items node and select Time Points.
A table appears in the top portion of the Time Points page listing all Time Points currently defined for
the current scope (if any). The Detail pane shows the properties of the current selection in the table.
5. Click Create New Time Point. A form appears where you can specify the properties of the new Time
Point.
6. Fill in the properties of the new Time Point and click Create.
Caution
It is possible to specify the same ID for Time Points defined in different scopes. For example, you could
configure a Time Point ID BETA1 for a project group (the parent scope), and configure a Time Point with
the same ID but a different date in a project in that same group (the child scope). The Time Points in
the project would then override those defined in the project group. However, this is not recommended
practice.
If a parent Time Point is removed, or a child Time Point is created, it is necessary to clear the system
caches.
You may wish to edit the properties of an existing Time Point, to extend the time or mark the Time Point
closed, for example.
Procedure
1. In the Administration interface, open the scope in which the Time Point is configured (Repository,
project group, project) and select the Time Point in the Time Points table as described in Creating a
New Time Point above.
2. In the Time Point detail pane, change any field in place (except ID) or click Edit to put all fields into
Edit mode.
You can only delete a Time Point if no Work Items are associated with it in their Time Point field.
A button labeled Delete appears in the Time Point page detail pane. If any Work Items are associated with
the Time Point, the Delete button is disabled and you cannot delete the Time Point.
If there were ever actually a reason to delete a Time Point after Work Items are associated (and this seems
unlikely), you would need to run a query to locate all the affected Work Items, and then use Bulk Edit to
remove the Time Point setting from all of them. You could then return to the Administration interface,
select the Time Point as has been described, and delete it by clicking the Delete button which should then
be enabled.
The Planning page enables administrators to set defaults for several data used by the legacy Live
Plan engine's calculations for how Work Items will be implemented. The legacy chart that rendered a
visualization of the implementation plan was removed from Polarion after browsers dropped support for
Adobe Flash. However, users can still enter data in project planning fields (Time Point, Initial Estimate,
Time Spent and Remaining Estimate, for example), and optionally create custom report Pages that utilize
the data.
The options on this page can be set in global (Repository) scope, and project scope, with some options
available only in global scope. Projects inherit the global settings until a project-scope configuration is
created.
Option Scope(s)
Default "Remaining Estimate" Value global, project
Query for Planned Work Items global, project
Roles for Dependency Relationships global, project
Roles for Parent Relationships global, project
Hours Per Work Day global
Enable Work Item Splitting global, project
Enable Due Date Planning global
The embedded Quick Help on the Planning page describes these options.
Procedure
Configure Prioritization
Several things relating to the prioritization of Work Items can be customized from the system defaults.
These include:
• Priority Ranks
• Priority Increment
Priority Ranks
When the standard Priority field of Work Items is used as the field for prioritizing Work Items, the priority
of a Work Item is a float value between 0.0 and 100.0. The higher the number, the higher the item's
priority. Polarion's default configuration provides priority ranks, which are simply text labels representing a
numeric range. The default values are:
Thus, an item with a Priority value of 75 has a priority rank of High, and an item with Priority value 49 is
ranked Low, and so on.
You can change the total number of ranks (add or delete ranks), the rank labels, and the rank Minimum
Value. For example, you might decide you don't need the rank Lowest, so you would delete that row in the
configuration page and adjust the Minimum Value field of the other ranks.
End users see the result of this configuration in the Priority field of Work Items, and in the Prioritization
sidebar of the Work Items table (used to reprioritize multiple Work Items at once).
Priority Increment
The Priority Increment value is used by Polarion when the position of an item in the table is changed by
using the Up or Down buttons in the Prioritization sidebar, or by dragging, to place the item at the top or
bottom position in the table. Such an item is assigned the numeric priority value of the item that formerly
occupied the top/bottom position, plus or minus the configured increment value. The default increment
value is 10. Thus, if a Work Item is moved to first position in the table, and the item that was in that
position before has a priority value of 50, the moved item would get a new priority value of 60.
If a different increment value is desired for such operations, system configuration can be modified to
use a different Priority Increment value. To change the default increment value, add the system property
prioritizationModeIncrement to the system configuration file polarion.properties (follow link if
you need the location). Set the property to an integer value. (As with any change to the system properties,
the Polarion server must be restarted before the change takes effect.)
Work Items have a standard multivalued field called Categories. By assigning one or more Category values
to Work Items, you add yet another parameter for ad hoc queries, reporting, and dashboards.
Category values are purely arbitrary — you can define any scheme that's appropriate to your needs using
whatever semantics you want. For example, you might define a Category named User Interface or Look &
Feel for all Work Items that relate to your application's user interface. You would then be able to query for
items having that value in their Categories field, and dashboards and report Pages would be able to report
information such as unresolved, or defect type items having the Category.
An administrator must define Categories before they can be assigned to Work Items. This configuration is
available only in the Project scope, as Categories only apply to individual projects, and not to all projects
globally.
Procedure
1. Log in with administrator permissions for the project you want to configure.
2. Enter Administration .
3. Open the project you want to configure.
A table appears in the top section of the page listing all Categories currently defined for the project (if
any). The lower section shows the properties of the current selection in the upper table.
5. In the toolbar of the top section of the configuration page, click the Create New Category button.
A form appears in the lower section of the page in which you can specify the properties of the new
Category.
6. Fill in the properties of the new Category.
• ID - an alphanumeric identifier that is unique in the project. (Required.)
• Name - the human-readable name that appears to end users in the pick list in the Categories field
of Work Items. (Required.)
• Description - a short text that explains the purpose of the Category. It appears to end users when
they hover over the Category in the Categories field of Work Items. (Optional - but recommended.)
7. Click the Create button to finish.
You can edit the properties of an existing Category, to expand the description, or make the name more
descriptive, for example.
Procedure
1. Open the relevant project, enter Administration, expand the Work Items node and select
Categories.
2. Select a Category in the Categories table.
3. In the Category's detail pane, click Edit. The data in the pane becomes editable.
4. Change the properties as desired. You can modify all except ID.
5. Click Save to save your changes.
You can only delete a Category if it is not assigned to any Work Items in their Categories field.
When editing an existing Category, the Delete button appears beside the Edit button. If any Work Items
are currently associated with the Category, the Delete button is disabled ,and you cannot delete the
Category.
If you really want to delete a Category that has been assigned to Work Items, you need to run a query to
locate all the affected Work Items, and then use Bulk Edit to remove the Category you want to delete from
the Categories field of all of them.
When there are no Work Items using a Category, you can delete it following these steps:
In addition to the default Work Item fields, you can configure custom fields of different types. For
information on supported field types, see Custom Field Types. Custom fields can be used to store
whatever data is needed to support your development process, and they can also serve as a parameter for
queries, providing an additional way to search for subsets of Work Items. You can define custom fields in
the global (repository) scope, or for specific projects. Within each scope, you can define custom fields that
apply to all Work Item types in the selected scope, or to one particular type of Work Item, for example a
Defect or Change Request.
Tip
If there is a single enumeration, click its icon to jump to the configured hyperlink.
If you are not familiar with the basics of the different scopes, you may want to review: The Administration
Interface. Custom fields are defined in one of several possible configuration files, depending on whether
you are defining custom fields applicable to all Work Item types, or to a specific type. The configuration
files are accessible in the Custom Fields topic of Administration under Work Items. The
configuration files can be edited online using the graphical web interface (recommended), or downloaded
and edited offline using an XML editor (recommended for advanced administrators only).
Custom field definitions applicable to all Work Item types are defined in the custom-fields.xml file.
Custom fields applicable to a specific Work Item type must be defined in a file of the same name prefixed
with the ID of the applicable type. For example, a configuration file for Requirement type Work Items
must be named requirement-custom-fields.xml (requirement being the type ID), for Defect
type items defect-custom-fields.xml and so on.
Warning
If a new *Required custom field is added to an existing Work Item Type:
If an existing Work Item type is amended so that a new custom field is *Required, then Work Items of
that type created BEFORE the new field was added can still be amended without entering a value for the
new field. (But you won't be able to clear a value in the field if one is already there.)
If you define a custom field of the Enum (enumeration) type, it needs to refer to an existing enumeration
which provides the values that appear in the field's pick list. Before configuring this type of custom field,
you should first create the enumeration to which it will refer. For example, if you want a project-scope
custom field Coffee from which users can select from among the values espresso, americano, and latte,
you would first need to create a project-scope enumeration containing these values before creating the
Coffee custom field in the project configuration. See Configure Enumerations and especially the section
Create Enumerations for Custom Fields.
Warning
Multivalued custom fields must be of the enum type.
The custom-fields.xml file in the global (Repository) scope defines custom fields that are the global
default for all Work Item types in all new projects. You then have the possibility to define custom fields
for different Work Item types (you should define all Work Items types before defining custom fields).
Configuring the different types in different scopes can seem a bit daunting for new administrators, but
once you grasp the concept it's not too difficult. Here are some common scenarios, and what you would
need to do in each case.
Scenarios:
Note
How global and project-level custom field configurations work together when combined:
• All project-level custom field types specific project-level types Both custom field
definitions appear in Work Items.
• All global-level custom field types specific global-level types Both custom field
definitions appear in Work Items.
• All global-level custom field types specific project-level types Both custom field
definitions appear in Work Items.
• All project-level custom field types specific global-level types Only the project
configuration for all types appear in Work Items.
Related Topics
Procedure
4. In the Navigation panel, expand Work Items and select Custom Fields.
5. In the row labeled - All Types -, click the Edit link in the Actions column to launch the Custom Fields
Editor.
6. Fill in the properties of the custom field you want to create.
If you want to create a multi-value field in which users can select multiple values in a drop-down list
of values, select Enum in the Type column, and select Multi.
Select Required if the new custom field should be mandatory. (End users cannot save Work Items
until all required fields are filled.)
Warning
If a new *Required custom field is added to an existing Work Item Type:
If an existing Work Item type is amended so that a new custom field is *Required, then Work Items
of that type created BEFORE the new field was added can still be amended without entering a value
for the new field. (But you won't be able to clear a value in the field if one is already there.)
7. To create additional custom fields, click the icon in the Actions column of the Custom Fields
Designer.
Tip
Tip for advanced administrators:
You may optionally use the custom-fields.xml link in the Custom Field Definitions section of the page
to download the global configuration file to your local system, and edit it with an XML editor to create
the desired custom fields definitions.
After editing the file locally, you use the controls in the Upload New Global Custom Field Definition
section to upload the modified file back to the Polarion repository.
Projects inherit the global configuration of custom fields. A copy of the global configuration file custom-
fields.xml is created in the project repository at the time the project is created. This file defines custom
fields applicable to all Work Item types. In any project, you can create a new project-scope configuration,
defining custom fields for all Work Item types, that applies only to the specific project and overrides the
global configuration of custom fields for all Work Item types.
Once a custom fields configuration for the project has been created, it can be modified to change field
types, required status, default value, etc.
To create a new project-specific custom fields configuration for all Work Item types:
Procedure
1. Log on with administrator permissions for the Project you want to configure.
4. In the Navigation panel, expand Work Items and select Custom Fields.
The link custom-fields.xml appears in the - All Types - row of the Custom Field Definitions table.
Depending on the project template used to create the project, the Type column shows Global
configuration and the Actions column is empty, or the Type column shows Project configuration
and the Actions column contains links named Edit, which open the project-specific settings), and
Remove, which removes the project-scope custom fields configuration for all Work Item types.
In the latter case, you can modify the project configuration or remove it and start over. For the
purposes of this scenario, assume there is no project-specific configuration for custom-fields.xml.
5. Click Create New Configuration. The Create New Custom Field dialog box appears.
6. In the Work Item Type list, choose -- All Types -- and click Next. The Custom Fields Designer page
displays. The file name of the configuration file you are working on appears in the header of a table
which provides data entry controls for each property of the new custom field you are defining.
7. Fill in the properties of the custom field you want to create.
If you want to create a multi-value field, select Enum in the Type column, and select Multi.
Select Required if the new custom field should be mandatory. (End users cannot save Work Items
until all required fields are filled.)
Warning
If a new *Required custom field is added to an existing Work Item Type:
If an existing Work Item type is amended so that a new custom field is *Required, then Work Items
of that type created BEFORE the new field was added can still be amended without entering a value
for the new field. (But you won't be able to clear a value in the field if one is already there.)
8. To create additional custom fields, click the icon in the Actions column of the Custom Fields
Designer.
9. Click Save to save the new custom field definition(s).
In the global scope, you can configure custom fields that apply to a single Work Item type. As mentioned
previously in this topic, the global custom fields configuration is inherited by new projects.
As an example, you might want to create a field Fixed in Build that appears in all new projects, but only in
"Defect" type Work Items.
To create custom fields applicable to a single Work Item type in the global scope:
Procedure
Warning
If a new *Required custom field is added to an existing Work Item Type:
If an existing Work Item type is amended so that a new custom field is *Required, then Work Items
of that type created BEFORE the new field was added can still be amended without entering a value
for the new field. (But you won't be able to clear a value in the field if one is already there.)
8. To create additional custom fields, click the icon in the Actions column of the Custom Fields
Designer.
9. Click Save to create the new custom field definition(s).
The procedure for defining custom fields applicable to a single Work Item type for a single project is
identical to that just described in the previous section for a single type in the global scope, except that you
should open the project you want to configure, as opposed to working in the Repository scope.
Projects based on a Project Template can have some preconfigured custom field definitions for the
Work Item types defined in the template. You may find that you need to modify an existing custom field
configuration for some Work Item type rather than create a new custom field.
Table type custom fields display a single table, with the columns and rows predefined in the field
configuration. You can create custom table fields for all, or specific Work Item types.
When configured as described below, the table type field appears to end users in the Work Item Editor in
the configured place in the form. Users can enter text in the cells and format it as they do tables inserted
into the Description field.
• You can configure table type custom fields in both global and project scopes.
• You can create and configure multiple table type custom fields for any or all Work Item types.
• The number of columns and rows in table type fields is not limited.
• Once implemented, table type custom fields can be restricted as read-only.
• Users cannot add attachments in table type custom fields.
Procedure
3. Click Edit in the Actions column of the Work Item type that you want to add a custom table field
to.
(Click Edit in the All Types row to add a custom table field to all Work Item types.)
4. Enter an ID and a Name for the table field and select Table from the drop-down list.
Not Configured and a Configuration link appear on the right.
5. Click Configure.
The Table Configuration dialog box appears.
Tip
After you define a table custom file it is necessary to add it to the Work Item Form (Editor) Layout
Configuration, so that it appears to end users.
1. In Administration, in the scope you defined the table custom field (Global or project), select Work
Items > Form Configuration .
2. In the Form Layouts section of the page, in the Actions column, select Edit on the row of the Work
Item type for which you defined the table custom field. (If you defined it for all Work Item types, select
Edit on the --Unspecific-- row.)
3. Add the field's ID to the Work Item section where you want it to appear.
When end users edit a table custom field in a Work Item, a formatting toolbar appears above the
table providing formatting options for table content.
If a Work Item in a Document contains a custom field of the Table type, the field's table appears in the
Document body, but users cannot edit the content there. In the context of a Document, table custom
A Rendering API for Table Custom fields lets you render a Table Custom field on a Live Report or
Info Page.
Procedure
</br>
$transaction.workItems.getBy.ids("drivepilot",
"DP-1657").fields.get("customTable").render
</br>
Replace drivepilot with your project ID, replace DP-1657 with your Work Item ID, replace
customTable with your custom table ID.
7. Click Apply.
8. Click .
The text/html field type is provided for custom fields. When you configure a custom field with this type
using the Rich Text (multi-line) option in the field designer, the field appears in the Custom Fields section
of the Work Item Editor as a multi-line text field with a toolbar enabling rich-text formatting of the field
content similar to the standard Description field). You can configure rich-text fields in either global or
project configuration, and you can limit the configuration to a specific Work Item type.
A use case for rich text fields is to provide storage for a translation of the content of the Description field to
another (human) language. This might be especially applicable to Requirement type Work Items. Consider
an example project configuration for this use case.
Note
• If the Work Item being editing is one that is stored in a LiveDoc Document, the Insert Table action is
disabled in the rich-text custom field toolbar and the user cannot insert any tables in the rich text field.
• If you want to add Images, Diagrams or Attachment Previews to a Rich Text field while editing a
Work Item, edit them in the Work Item Editor, not using the Inline editing feature.
(You can see Images and Diagrams when editing Rich Text fields inline, but you cannot Preview
them or edit Diagrams.)
• Rich-text fields in Test Runs cannot use features that depend on attachments ( Attachment
previews and Diagrams).
(So, Diagrams are not supported for rich-text Custom Fields in Test Runs. The Insert Diagram
toolbar action is hidden and users cannot insert diagrams.)
Consider this scenario: you have a custom field for Defect type Work Items named "Affected OS", of type
enum, with enumeration values Linux, Windows, and OS-X. You have another custom field "OS Version",
also of type enum, which holds different versions of the operating systems listed in the "Affected OS"
enumeration.
By default, when your users choose Linux they would have to pick the value from a list that includes
not only Linux versions, but also Windows and OS-X versions, because all these are in the "OS Version"
enumeration. The list could be large, so it would be better for users if the enumeration values shown to
them in the "OS Version" field were dependent upon the user's selection in the "Affected OS" field. That is,
when users pick Linux, they should only be shown values like SuSE, Ubuntu etc. in the "OS Version" field.
Polarion provides a feature "Dependent enum Fields" that enables administrators to easily set up this kind
of usability for end users. Note that it is only for custom fields.
You can configure Dependent enum Fields both globally, and per-project. The process has 2 main steps:
Procedure
The first step is to configure the necessary enumerations in Administration. For the example scenario
above, you would define one enumeration containing the names of operating systems (let us say,
opsystem-enum.xml), and another containing the versions (osversions-enum.xml). The objective
here is to create a value dependency between them. The values shown to users from the latter will depend
on the value selected in the former.
Procedure
3. Map the dependency between the enumerations. Open either of the enumerations in the editor, and
use one of the two dependency selectors to select the other enumeration, and create a mapping of
values.
This may be easiest at first if you open the enumeration whose selection filters the values from the
other one. In our example, this would be the opsystem-enum.xml enumeration (because when a
user selects, for example "Linux", that selection should result in showing only Linux versions from the
osversions-enum.xml enumeration). Therefore, you would go to the Enumerations depending
on this one section and select osversions in the list.
4. Now click the Add Mapping link. In the mapping dialog box, select the first value of the current
enumeration in the left-hand list, and in the right-hand list select all of the dependent values that
5. Repeat this mapping for all the other values in the current enumeration, selecting only valid
dependent values in the right-hand list.
After creating the necessary enumerations and mapping dependency between them, you must still create
custom fields and associate them with the enumerations.
This section explains how to create custom fields that use the enumerations described in the previous
section.
Procedure
1. Configure two custom fields for the desired Work Item type, or all types is that is what you need
(Navigation: Work Items > Custom Fields). Name them in such a way that the first suggests that it is
the parent or main value on which the second depends.
In our example scenario, you would create a custom field "Affected OS", of type enum, selecting
the opsystem enumeration. Then you create another custom field "OS Version", also of type enum,
selecting the osversions enumeration.
Tip
If you do not see the list for selecting the enumeration, enlarge the Type column by dragging its
header to the right. Enlarge until you see the enumerations list and the (Configure Dependency)
icon.
2. Click the (Configure Dependency) icon on the row of the dependent field (the field whose values
you want filtered for the user). The Depends on field appears. In that field, select name of the
"parent" field.
In the example scenario, you would click on the "OS Version" field, and in the Depends On field,
choose Affected OS.
3. When you select a value in the Depends On field, the Mapping filed appears. Select the mapping you
specified when configuring the enumerations. (It is possible to have more than one mapping for an
enumeration pair. If there are multiple mappings, select the one you want to use for this field pair.
You can optionally create a new enumeration mapping now, using the Add Mapping link, or modify
the selected mapping using the Edit link.)
Enumerations defined for all Work Item types in the General Configurations section can be redefined
specifically for each Work Item type. Because of this, the mapping dialog behaves a little differently
depending on the type of or enumeration custom field definition it was opened from:
If multiple definitions of the same enumeration define an enumeration option with the same ID, it will
be displayed only once in the mapping dialog. If these enumeration options sharing the same ID have
different Names assigned, all of these Names are listed in the mapping dialog. Hovering over each of
these comma-separated names will reveal a tooltip with the source information for that name (General
Configurations, or a Work Item type name).
Note
Enumeration mappings are always shared between the type-specific and General configurations.
Editing the mapping in the type-specific context will also affect the behavior of that mapping in the
non-type-specific context, and vice-versa.
You may remove a custom field from the configuration, or change its type. In the case of a field of type
Enum (enumeration), the field can be changed from single-value to multi-value. If you change custom field
type, existing values in Work Items may become incompatible with the new type or simply invalid. You can
check for such problems by running a query in the Table view of the Work Items topic when a project is
open:
Configure Enumerations
About Enumerations
Enumerations are basically lists of values that can be selected and applied by end users as a value to some
field of a Work Item. Typically, enumeration values appear as choices in a list control. The Severity field is
a simple example. Values for this field are specified in an Enumeration, specifically in the configuration file
named severity-enum.xml, accessible in the Work Items Enumerations topic of Administration. The
values can be configured globally as defaults for new projects, and per project, where the values override
the global configuration. Values can be applicable for all Work Item types in a given scope, or to one or
more specific types.
Severity values for some type of Work Items in a software development project might be something like
the following:
• Must have
• Should have
• Nice to have
• Later
• Never on this planet
Values for Enumerations are stored in XML files that are named according to this convention: [field
ID]-enum.xml. For example, values for the Priority field are defined in priority-enum.xml, for the Status
field in status-enum.xml, and so on. If you create a custom field of the enum (Enumeration) type, you
need to create an Enumeration file named similarly: [custom field ID]-enum.xml where [custom
field ID] is replaced by the actual ID of your custom field. For example, for a custom enum field named
Coffee, whose ID is coffee, the Enumeration file must be named coffee-enum.xml.
Tip
The default Enumeration files for the Repository scope are listed in: Default Enumeration
Configuration Files
In both the global (Repository) and project scopes, Enumerations apply to all Work Item types by
default. However, in either scope, Enumerations can be defined to apply to a single Work Item type
— Requirement, Task, or Defect, for example (assuming these types exist in the scope). The file naming
convention for type-specific Enumeration files is: [work item type ID]-[field ID]-enum.xml.
For example, assume that the Enumeration values for the Severity field were preconfigured by a Project
Template when the project was created. By default, the values specified in severity-enum.xml are used for
all Work Item types in the project. Now, suppose you want a different set of Enumeration values for the
Severity field of just one Work Item type, named Defect (with ID "defect"). You would need to create a
type-specific Enumeration file for that type, named defect-severity-enum.xml.
Tip
You can find the IDs of Work Item types in Administration Work Items Types.
Warning
If you create enumeration configuration files outside of Polarion, and upload them to the repository,
do not use the literal workitem-type in the file name. If you do, Polarion treats it as a Work item type
definition rather than an Enumeration definition.
For example, if you create a file named defect-workitem-type-enum.xml (for the purpose of classifying
Defect type Work Items), and in it you define two values UI Defect and Functional Defect, your project
would have two new Work Item types with those names, and not a new Enumeration with those values.
The online option provides graphical controls in the browser enabling you to define new Enumerations or
edit existing Enumerations. All work is done online using your web browser, and changes are written to
the underlying XML files. This is the recommended approach for most administrators, and the rest of this
topic is based on this approach.
The offline option involves downloading a local copy of some existing XML configuration file, modifying it
locally using an XML editor, and uploading an appropriately named copy of the file back to the portal. This
is recommended only for administrators who have knowledge of XML and the XML schema involved.
The configuration process is essentially the same for both global and project scopes. Just remember that
new projects inherit the global configuration, so it's usually a good practice to configure the global defaults
before customizing any projects. The basic process is as follows:
Procedure
1. Log on with administrator permissions for the scope you want to configure.
2. Open the repository or project you want to configure, and enter Administration.
(Click Administration in the tool view of Navigation, and select Work Items
Enumerations.)
The Enumerations page presents a table of the existing Enumeration configurations for the current scope.
On this page you can do the following:
• View the underlying XML code of any configuration file by clicking the file name in the Configuration
column.
Caution
If a value has already been applied to Work Items, changing its ID is not recommended. Keep the
existing ID and change the Name.
Caution
If a value has already been applied to Work Items, removing it from the Enumeration is not
recommended. If the field where it is used is a required field, an error may result. You should query
for Work Items that have the value in the relevant field, and change those items to a different value
(perhaps using Bulk Edit) before removing the value from the Enumeration.
• Change the order of rows in the table. (Left click on beside a row and drag it to the desired position.)
Enumeration values appear in lists in the order they appear top-to-bottom in the table.
• Configure dependent Enumerations.
Using the graphical user interface to edit Enumerations is recommended for most administrators.
However, there is another option for administrators who know XML and may prefer to edit the XML
configuration files directly using a preferred editor application. If you prefer to work that way, follow these
steps:
1. Be sure you are working in the scope you want to configure, and open Administration
Work Items Enumerations.
2. On the Enumerations page, right-click on the file name of the XML configuration file you want to
modify. Then, on the context menu, select your browser's command for saving a linked file - Save link
as... for example. Save the file to a convenient location on your computer.
3. Modify the downloaded XML file as desired, using a text or XML editor application.
4. Return to the Enumerations page, scroll to the bottom, and under Upload New Project
Configuration, select Choose File.
5. Navigate your computer's file system and select the XML configuration file you modified locally.
6. Select Upload to complete the configuration process.
Your Polarion installation has predefined global default Enumeration configurations for some Work Item
fields. For a list of all default Enumerations, see the reference topic Default Enumeration configuration
files. The listed Enumerations apply to all Work Item types unless overridden by a type-specific
Enumeration. In a new installation, there are no type-specific Enumerations unless you opted to install
the example projects (Demo Data) during initial installation. In that case, the installer adds type-specific
Enumerations for some of the Work Item types in those projects, and they are displayed on the global
Enumerations page.
Tip
Always keep the scope in mind when configuring Enumerations. The Enumeration values configured in
the global scope will be the default for all subsequent new projects.
Procedure
Caution
This is a scenario for new installations where no enumeration values have been applied to Work
Item fields yet. If the system has gone to production, and a value has already been applied to Work
Items, removing its row from the Enumeration is not recommended. For more information, see Edit
an existing Enumeration.
5. Click Save to save changes to the underlying XML configuration file and return to the Enumerations
page.
You can create enumerations that apply to only one Work Item type in either scope (global or project).
Before doing this, you must configure the Work Item types in the desired scope in the Work Items
Types page of Administration.
Tip
Advanced administrators may prefer to perform the same configuration in workitem-type-enum.xml in
the Enumerations page.
1. Be sure you are working in the scope you want to configure ( Repository or Project).
2. Click Create configuration at the top of the Enumerations page ( Administration Work
Items Enumerations ).
The Create New Enumeration dialog box is displayed.
3. In the Work Item Type list, select the type to which this new Enumeration should apply, for example
Requirement or Defect.
Note
If the desired Work Item type does not appear in the list, it means that the type does not exist
in the scope where you are working. Make sure that you are working in the correct scope. If
you are, and the type doesn't exist, you need to configure Work Items types before configuring
type-specific Enumerations.
4. In the Enumeration list, select one of the already-defined enumerations, or select Custom: and enter
an ID for a new enumeration to apply to this definition, then click Next. If you selected an existing
Enumeration, the enumeration editor appears with the values from the all-types configuration. If you
selected Custom, the enumeration editor appears with a single new empty row where you can define
values for a new enumeration for the Work Item type you are configuring.
5. Edit the Enumeration definition in the Enumeration Designer by adding, removing, or changing
values in the various table rows as desired.
6. Click Save to create a new type-specific configuration file in the repository that contains the values
you defined.
Note
After you define an enumeration for a Work Item type, you have to define an enum type custom field
for the same Work Item type (if one does not already exist), and then select your enumeration as the
applicable one for the custom field. The enumeration values then appear in the field in the Custom
Fields section of Work Items (or wherever you configure it to appear in the form layout).
Custom fields can be of the enum (Enumeration) type. This type of field has a list of valid values that end
users can choose from. The select-list values for such custom fields must be defined in an Enumeration.
Custom enum fields can only use an existing Enumeration, so you must define the relevant Enumeration
before a custom field can use it.
1. Be sure you are working in the correct scope ( Repository or Project) for the configuration.
2. Click Create configuration at the top of the Enumerations page ( Administration Work
Items Enumerations ) and create a new enumeration.
3. In the Create New Enumeration dialog box, select which type of Work Item the enumeration is for,
or choose -- unspecific -- to make it applicable to all types. Then in the Enumeration field, choose
Custom: and enter a file name prefix for the new Enumeration's XML file.
4. Click Next. The Enumeration Designer page opens with an empty row, ready for you to add values
to the new Enumeration.
Tip
If there is a single enumeration, click its icon to jump to the configured hyperlink.
5. Enter the desired Enumeration values and click Save. You now have the Enumeration defined and
ready for your custom field to use.
As mentioned earlier, projects inherit the globally defined Enumerations. Project administrators can
override the global enumerations in projects in any or all of the following ways:
Polarion comes with a set of icons for enumerations and other configurations. You can add your own icon
images and use these in new enumerations, or to replace the default icons in existing enumerations.
Icon images must be 16 x 16 pixels. Supported formats are: GIF, PNG, and JPG. Custom images are
saved in the Others group of the Project icon set or the Repository icon set, depending on the scope
you are working in when you upload your custom image(s). Within the icon sets you can save icons in
custom groups by prefacing the file name with the name of a group that it belongs to. For example,
if you want to save an icon named myIcon1.png in a group named Widgets, rename the file locally as
Widgets_myIcon1.png and upload the renamed file.
Procedure
1. Access the Enumeration Designer page for the enumeration in the scope you want to configure
(Work Items Enumerations Edit).
2. In the row for the value that you want to display a custom icon, click Select in the Icon column. The
Select Icon dialog box appears.
Over time, the values specified in some enumerations may become obsolete. You can delete obsolete
values, but if such values have already been used in Work Items, you may still want the values to appear in
the items for your historical record for traceability and governance reasons. In this case, simply deleting a
value from the configuration to keep it out of the list is not the answer.
Instead, you can select the check box in the Hidden column on the value's row in the configuration page.
When this column is selected, the value still appears in the Work Items where it was used, but end users
will no longer see it in the field's select list, and consequently won't be able to specify it for any new or
existing Work Items.
This is probably the most common customization. Work Items can represent literally anything. If you have
a project in which you need to deal with things you call Supply Chain Risks you can create a Work Item
type named Supply Chain Risk with whatever attributes you need for it to have.
(The same settings are also accessible in Work Items Enumerations in workitem-type-
enum.xml.)
Priority ranks
By default, the Priority field of Work Items can be set by selecting one of several configured ranks, such
as High, Medium, and Low, which correspond to a configured minimum numeric value. Many teams
prioritize Work Items according to different ranking — more or fewer ranks than the Polarion default —
and will therefore need to reconfigure the prioritization.
Dependent Enumerations
You can create custom enumeration pairs with a value dependency between them. When used as
the type for a pair of custom fields, the selection of a value on one enumerated list causes some
filtering of the values in another, limiting the choice of values for the end user. It is possible to create
multiple dependency mappings between pairs of enumerations for use with different scenarios. The
administrator can choose which mapping to use with any pair of custom fields associated with the
dependent enumerations.
For information on how to configure this functionality, see Custom Fields with Dependent
Enumerations.
Note
Query Enumerations in a Database:
See the Advanced Administration topic to populate an enum table so that it can be used with an
external reporting tool.
The Inline Editing feature lets your users edit some Work Item fields directly in the Table and Tree
Work Item tables.
It is enabled by default, but if you want to disable it, add the following property to the polarion.properties
file:
com.siemens.polarion.ui.inlineEditingInWiTable.enabled=false
Caution
Read-only fields set in the Work Item form layout form like the following can still be edited inline in
Work Item tables:
See Define Read-only fields to create fields that are also read-only inline.
The Bulk Edit feature enables users to select multiple Work Items and edit, move, or delete them as a unit.
Administrators can set a limit on the number of Work Items selected before the restricted Bulk Edit mode
is activated. Restricted Bulk Edit loads less data and therefore minimizes the load on the server when a
user selects a large number of Work Items for bulk editing.
You can set the limit with the system property com.polarion.ui.bulkEditRestrictedLimit, in the
polarion.properties file.
The value is an integer representing the number of Work Items users can select in the Work Items table
before restricted Build Editing is activated.
Example: com.polarion.ui.bulkEditRestrictedLimit=100
A template Work Item is a Work Item that provides default content such as Description, and default field
values for a specific Work Item type. For example, the template item for a Defect or a Test Case might have
boilerplate text in the Description field, and/or some specific values set for fields such as Assignee, Priority,
etc. or custom fields.
Before creating a template Work Item, its type must already be defined in the project configuration. In
other words, before you can create a template item for a Defect, the Defect type must be defined in the
enumeration for Work Item types in the project configuration.
Once the Work Item type exists, there are 2 steps to create a template Work Item:
Procedure
1. Create a Work Item of the desired type in the tracker and define default content and field values.
2. Specify the ID of the template item in the definition of the Work Item type in the project
configuration.
Procedure
1. Log on with administrator permissions and open your project if not already opened.
2. In Navigation, select Work Items to load the Table view of Work Items.
Procedure
1. Enter Administration and in Navigation, expand Work Items and select Enumerations.
2. On the Enumerations page, locate the row for the workitem-type-enum.xml configuration file
and click Edit on that row.
3. In the configuration editor, locate the row for the type of the template item you created. If that was a
Defect type item, for example, you want the row for the Defect type.
4. In the Template column on the row, enter the ID of the template item you created.
(You can optionally click the icon and query for and select the template item in the Work Item
picker dialog box.)
5. Click Save to finish.
You need to repeat this entire process for each Work Item type for which you want to have a template Work
Item.
When a user creates a new Work Item based on a template Work Item, values in the following fields of the
template item are not copied to the new item:
• approvals
• assignee
Note that images are technically attachments, which currently are not copied to new items. Therefore,
images appearing in the Description field and rich-text custom fields of the template item do not appear in
these fields of new items.
Polarion provides templates which are applied by default to exported documents when users export Work
Items to various supported formats. The default templates can be customized, or you can create one or
more customized copies of the default templates (recommended).
Export Templates are initially in the Repository scope and used for new projects. If you customize Export
Templates in the repository scope, the customizations are the default in new projects. Export Templates
can be customized in projects and project templates, and the project-scope template overrides the
Repository-scope version of the same template in the project, or in projects based on a project template in
which Export Templates have been customized.
The Administration interface provides access to Export Templates in the Repository or projects. You can
download any existing template, upload custom templates, or delete existing templates.
Procedure
1. Log on with administrator permissions for the scope you want to access. If logging on does not
automatically take you into Administration, enter Administration using the link in the tool view of
Navigation.
2. Open a repository (to access global repository templates) or a project.
The Export Templates page lists available export formats in the left-hand column. When you select one of
these, icons for the existing Export Templates for the selected format appear in the right-hand column.
Procedure
Tip
You can optionally use the Repository Browser to upload modified Export Template files to the
export_templates folder of the project's repository ([PROJECT_NAME]/.polarion/tracker/
export_templates).
Caution
We updated the Formatting Objects Processor (FOP) in Polarion 21 R1. Some previously created
XSL-FO Work Item Export templates may need to be updated.
For additional information, see Customize XML Export Templates and Customize export templates for
Microsoft Excel.
Administrators can customize which Plans appear in the Planned In list using a velocity script.
• $wi - The Work Item variable. Can filter for results based on Work Item fields. (Status, Severity, Priority,
Type, Assignee, Author, Custom Fields etc.)
• $user - The User variable. Can filter for results that are only relevant to the current user. (Name, E-mail,
Role etc.)
Note
Only Lucene queries are supported.
Procedure
4. Click Save.
Polarion provides a query as the default filter for the items listed in the Planned In field.
For example, if your project uses the E-Library template, the query is:
Examples:
status:open
template.id:iteration AND
#if ($wi.getStatus().id == "draft")
status:open
#else
NOT HAS_VALUE: finishedOn
#end
Lists Plans with a status other than Done. Only the Work Item Assignee(s) can view/change them.
#if ( $wi.getAssignees().contains($user) )
template.id:iteration AND (NOT status:done)
#else
NOT status:(open inprogress done)
#end
You can define fields that derive their value from a calculation based on the values of other fields in the
same (or child) Work Items. Here are several key concepts to keep in mind:
• Calculated fields are only available in the HEAD revision of Work Items.
• Aggregation of the values is always done according to a parent-child hierarchy of linked Work Items
defined by links that have a role which has the attribute parent set to true in roles configuration file
workitem-link-role-enum.xml (found in the Work Items Enumerations topic.)
• A Calculated field's Type must be the same as that of the fields from which it is calculated. Supported
types are: integer, float, currency, duration.
• Their values are calculated asynchronously and incrementally after each commit.
• They appear as read-only fields in Polarion and are not modifiable by end users.
• They can be configured for the Global, Project and Work Item type scopes.
Note
Because On-demand Work Item loading items are loaded from baselines, Calculated Fields will not be
visible in a Document when On-Demand Work Item loading is enabled.
(They will still be visible in the Work Item Properties Sidebar and the Work Item Editor.)
• Calculated fields are not committed to the underlying repository, and are therefore not available in a
Work Item's history. (Except in backlinks in the Collections context.)
• They are not stored in the HEAD or historical sections of the database.
• They not searchable via Lucene or database queries in the history.
A common use case for calculated fields is the calculation of the cost of a set of Work Items. For example,
a project could have a custom field named Cost, configured for Work Items of a type named Task, and a
field named Total Cost configured for Work Items of a type named Requirement. Requirement items would
be linked to the Task items that implement them with a link role named parent, defined in the project
link roles configuration. Alternatively, this could be done with just Tasks. Both custom fields could be
configured for Task items, which can be linked so that subtasks are children of a main task. The aggregated
cost of the subtasks is then reflected in the Total Cost field of the linked tasks. Using the latter example of
Task-to-Task, the steps to realize this use case are as follows:
• Make sure that the parent role has the parent flag set in link roles configuration.
• Define custom fields to become calculated fields, in this case Cost and Total Cost, making sure they are
of the same data typeculatge required for the <sum> calculation.
• Configure calculated fields that reference the custom fields.
For this use case, you would need to configure two custom fields, probably in the project scope. In the
Administration Work Items Custom Fields topic, you would enter the following using the
Custom Fields Designer:
Create a new row in the table for the next custom field and enter the following:
• ID: totalCost
• Name: Total Cost
• Type: float
• Description: Aggregate cost of all linked tasks
You now need to reference the IDs of the custom fields appropriately in the Calculated Fields topic in the
appropriate scope of calculated-fields.xml:
Procedure
For example, if Work Item B is linked to Work Item A with role parent (that has parent flag set), and there
are no other linked Work Items, and Work Item B has cost value of 10, and Work Item A has cost value of
20, then the calculated values in Work Item B will be totalCost = 10, and in Work Item A totalCost = 30.
Other use cases can make use of several of the standard Work Item fields. For example, you could set
up a calculated field Total Remaining Time that would aggregate the values of the remainingEstimate
fields in a set of parent-child linked Work Items. Alternatively, at the beginning of a new project you could
create a Total Estimated Time field that sums the values of the initialEstimate field of a set of Work Items.
Remember that calculated fields can be included in exported Work Item reports. Values will be current as of
the date-time of the export.
If you need to modify an existing calculated field configuration, you can do so. Be sure you are making
changes in the right scope.
Procedure
1. In the Administration interface, select the scope of the configuration: Open Project or Project
Group dialog box. (See Access Projects.)
2. Expand the Work Items topic and select Calculated Fields .
3. In the Calculated Fields page, click the Edit button in the Actions column of the calculated field you
want to modify, and make the desired changes in the Calculated Fields Configuration page.
4. After saving the changes, click the Recalculate Fields at the top left of the Calculated Fields page.
Note
This topic covers Work Item workflow configuration.
You can also configure worfklows for Documents and Test Runs.
Warning
• Workflow definitions and status enumeration work in tandem.
• Type-specific and generic enumerations should not be mixed together.
(This also applies to Project and Global Definitions.)
A workflow consists of a set of named statuses and status transitions, transition conditions and
dependencies that a Work Item passes through in its life cycle. For example, consider the following set of
status definitions:
Procedure
If a user changes the Work Item's status from Open to In Progress, or Open to Resolved, this invokes
an action, which triggers a status transition, which is automatically tracked in the Work Item's History.
Actions may trigger underlying system functions — creating a linked Work Item, or clearing some field's
value, for example. Workflow actions can be conditional. That is, some condition must be checked and
fulfilled before the user can perform the action.
You can customize Work Item workflows and transitions in several scopes: globally (for all projects),
project-specific for individual Projects, and/or Type-specific, which applies only to a specific type of Work
Item in a project. (Type-specific can be configured both globally and in projects.) Polarion looks for the
most specific workflow definition first and proceeds toward the most generic in the following search
sequence:
Procedure
3. Project-specific
4. Global
Procedure
1. Configure Work Item custom fields: define any that are needed for Work Items in the scope. If your
workflow will not have any functions and conditions that reference Work Item custom fields, you can
skip this operation.
2. Configure Statuses: Determine the statuses a Work Item can have at various stages of its lifecycle —
Draft, In Progress, and Implemented, for example. Then create a Status definition for each one in
the Statuses section of the Workflow Designer.
3. Configure Actions: Determine what actions are needed to transition a Work Item from one status
to another throughout your development process, give them brief but intuitive names, and create an
Action definition for each one in the Actions section of the Workflow Designer.
Action names appear in the drop-down list of a Document's Status field in the Document Properties
sidebar. The name indicates to the user what transition takes place as a result of invoking the Action.
For example, an Action named Mark as Implemented can be defined for the transition of a Work
Item from the status In Progress to the status Implemented.
4. Configure Functions and Conditions: Optional. You can specify one or more programmatic
functions that the system should run when an Action is invoked by users, and specify conditions
that must be satisfied before in order for the specified functions to run.
5. Configure Transitions: Now you can specify how the Work Item transitions from one status to
another in the Transitions section of the Workflow Designer page (see Using the Transitions
Matrix).
Workflow Designer
A graphical Workflow Designer tool is provided in the web interface. It presents a visualization of workflow
configurations and related enumerations such as status definitions. The Workflow Designer is available in
all of the available scopes.
To access the Workflow Designer tool, you need to go into Administration for the scope you want to
customize (global or project). If you want to configure Global workflows, select Repository in the Open
Project or Project Group dialog box. Keep in mind that changes will apply not only to new projects, but to
all existing projects unless a project-scope workflow configuration has been defined for them individually.
To configure workflow for a specific project, select the project in the Open Project or Project Group dialog
box after entering Administration.
Once you are in the desired Administration scope, go to the Navigation pane, expand the Work Items
node, and select Workflow. The Work Item Workflow page opens and displays a table of existing and
available workflow configurations.
Workflow configurations table shows existing configurations, and provides access to the Workflow
Designer.
The first row of the table is labeled -- All Types --. This is where you can define a default workflow for all
Work Item types in the scope that do not have an overriding type-specific workflow configuration defined
for them. The Type column indicates whether or not a type-specific workflow is configured for that type in
the current scope. If a cell in that column is empty, it means no workflow is configured for the Work Item
type shown on that row, and the All Types workflow will be used.
The Transitions section at the top of the Workflow Designer is a matrix of workflow transitions between
Work Item statuses. The direction is from row to columns. For example, the value where the row Open
intersects the column Resolved represents the transition from the Open status to the Resolved status. At
each intersection where a transition is possible, there is a list of Actions.
The Actions are defined in the Actions section of the designer. When end users want to transition a Work
Item to a different Status, they select the appropriate Action in the Status field of the item. For more
information, see Using the Transitions Matrix.
The Statuses section is an enumeration editor for defining workflow Status definitions for the scope in
which you are working.
This is an editor for transition Action definitions. Action names that appear in the drop-down lists in the
Transitions matrix are defined here. The Required roles, Required fields, and Cleared fields columns are
comma-separated lists of role IDs and field IDs. Only simple fields are supported.
Caution
• Work Records, Votes, Watches and other collection fields are not supported as Required fields for a
workflow.
(See Configure Work Records to set them as Required fields for a Work Item).
• Do not set the following fields in the Cleared Field option: (Polarion ignores them or produces
unexpected results.)
The Initial column in each Action row enables you to specify one Action as the first action that must occur
in order for the Work Item to enter the Status defined as the initial status when a new Work Item of the
applicable type(s) is created. (Defining an Initial status is required.) Specifying an Initial action is mainly
important if some fields must be marked as Required, and/or some field(s) must have value(s) cleared,
and/or some workflow function must be run before the defined initial status (Draft, for example) is applied
to a new Work Item. If no Initial action is specified, then no fields are changed and no workflow function
runs when a new item is created, even if the Action has these defined. Field changes and workflow
functions only take place when the Action is invoked manually by changing the Work Item's status.
The Conditions and Functions columns in each Action row indicate if any workflow conditions and
functions are configured for the action.
Tip
For a list of the available conditions and functions that can be specified for Work Items, see Workflow
Conditions and Functions.
The Actions column in this section of the designer contains two icons. The icon invokes the Action
Details dialog box, which provides tools for defining workflow functions and conditions to be run when
the Action is invoked.
It can be helpful to your end users if you specify the Name property of an action as a verb or verb
phrase. For example, if you have Implemented and Verified statuses, and you want to define Actions
for the transition from some other status(es) to these statuses. For transitions to the Implemented
status, a good choice for the Action name would be Mark as Implemented as opposed to just
Implemented. The same idea applies to the Verified status. The transition Action name might be
Verify Implementation or Mark as Verified.
In the Required Roles field you can enter a comma-separated list of roles that a user has to have in order
to be able to invoke the Action. These roles may be either the project or global user roles project_admin or
admin, or two special system roles:
• workitem.assignee - only the assignee of the Work Item has this role
• workitem.author - only the author of the Work Item has this role
Valid role names are all the global and project roles (admin, user, for example) in the same form as in User
Management - Roles. There is no need to prefix them with a project ID, because they are always resolved
against a given Work Item's project. The only permitted logical role is workitem.assignee. Roles have OR
logic - one match is enough for the condition to succeed.
When defining transitions using the Workflow Designer's Transitions matrix, it's important to keep two
things in mind:
• You are defining what transitions are allowed between any 2 statuses
• Therefore, you don't need to specify an action for every transition, just those transitions you want to
allow to occur between two statuses
Consider an example of a workflow for a Requirement. Assume that, among others, the statuses Draft
and Awaiting Review are defined.
No transition Actions
Allow and disallow transition to take place between two Work Item statuses
It makes sense to allow transition from the Draft status to the Awaiting Review status, so at the
intersection of these two, you specify the Send to Review action (which has already been defined in
Actions).
It would not make sense for the process to allow transition directly from the Draft status to the
Reviewed status (assume the team process does not allow this), so no action is specified where Draft
intersects Reviewed in the matrix.
For some status, you may want to have more than one possible transition. For example, suppose you
have the status definitions Implemented, Verified, and Needs Changes. For Work Items having the
Implemented status, let's say there are two possibilities in the process: QA can pass the item and give
it the Verified status, or QA can reject the item and send it back for changes, giving it the Needs
Changes status. The workflow can be configured to support this process but allowing 2 transitions on the
Implemented status.
• Transition from Implemented status to Verified status via the Mark as Verified action.
• Transition from Implemented status to Needs Changes status via the Reopen action.
Where it makes sense for your process, enable more than one transition for a status
Polarion's standard project templates are preconfigured to support a formal approval process. Even if the
overall process as configured meets your needs, there may still be some things you want to adjust in the
approvals workflow. For example, the default configuration includes a workflow function on some Actions
that automatically adds users to the Approving Users table of the Actions field of Work Items, resulting
in notifications to those users. However, the users so added by the default settings may not be users you
actually want, or there might be other users you want included that are not.
Basically, for each Work Item type you should review the Actions that relate to the approval process in the
Workflow Designer. For example, for a requirement, click Editfor the Send to approve action. By default,
this Action invokes a workflow function AddDefaultApprovals, which automatically adds some users
to the Approvals field of Work Items when the Send to approve action is invoked.
By default, this function uses the approvals.roles parameter with a single value
project_approver. This means that when the Action is invoked, all users whose user profile includes
the project_approver role are added to Approving Users table in the item's Approvals field. If this is
not what you want, you can either change the role, or add more roles, or use the approvals.users
parameter instead. (For more information, see Workflow Functions.)
Another Action to review might be Back to Draft. By default, this Action invokes the workflow function
ResetApprovalStatus. Perhaps you want to invoke some other function after that — SetDate, for
example.
You can require end users to electronically sign when invoking a workflow action to transition to a new
Status.
In the Actions section of the Workflow Designer, each action has a Requires Signature check box
option. Selecting this option means that a user invoking the Action is requested to provide an electronic
signature, and the workflow transition cannot take place until a signature has been logged.
To configure this functionality, you need to edit the following properties in the system properties file
polarion.properties (follow link for location):
• secure.approvals: The value is a Boolean true or false (the default value is false). If set to
true, then when an end user performs an approval or disapproval Action, the password dialog box is
presented as described above.
Example: secure.approvals=true or secure.approvals=false
• secure.dialog.title: The value of this property is a string of characters. The string appears as
the title of the password dialog box presented when an end user invokes one of the configured secure
workflow actions. You only need to set this property if you want to override the system default title for
the dialog box (shown in the example below).
Example: secure.dialog.title=Enter Password
• secure.dialog.message: The value of this property is a string of characters. The string appears as a
message in the password dialog box presented when an end user invokes one of the configured secure
workflow actions. You only need to set this property if you want to override the system default message
for the dialog box (shown in the example below).
Example: secure.dialog.message=By entering my password I signify that I have
reviewed and approved the content of this individual Work Item, or group of
Work Items, just as I would have by applying my own handwritten signature.
Tip
◦ For security, it is highly recommended to use the HTTPS protocol for access to Polarion when your
system is configured to use electronic signatures.
◦ If a Status change requires an electronic signature, you must change it in the Work Item Editor.
(You cannot change it inline via the Table and Tree Work Item tables.)
Caution
Your browser might offer to or autofill credentials in forms like e-signatures that use password fields.
Edit your browser settings or enforce the related security policies on managed computers to disable
this.
You can enable secure approvals that require electronic signatures to satisfy compliance or governance
requirements.
Tip
See Electronic signatures for details on how to configure LDAP or other external providers to
authenticate electronic signatures.
You can override the signature approval messages for the below properties directly in the
polarion.properties file.
You don't have to dig through and change the localization messages file.
(For example,
the C:\Polarion\polarion\plugins\com.polarion.psvn.translations.en_3.18.2\META-
INF\messages_en.properties file for English.)
Tip
Non-ASCII languages should be converted to Unicode.
Procedure
This enables secure approval comments using the default (English) messages.
(If it's not present in the file, add it on a new line.)
4. Add the following properties with your custom messages .
(Customize the default messages after the = character.)
• secure.approvals.comment=Your custom message
Overrides the dialog.secure.comment=Item was e-signed value in the localization
messages file.
• secure.approvals.comment.text=Your custom message
Overrides the dialog.secure.comment.text=Approval verdict: $img {1} value in the
localization messages file.
(Where {1} is the verdict text.)
• secure.approvals.comment.onBehalfOf=Your custom message
Overrides the dialog.secure.comment.onBehalfOf=Approval verdict: $img {1}
(on behalf of {2}) value in the localization messages file.
(Where {1} is verdict text and {2} is the user that the approval was done on behalf of.)
5. Save your changes and close the polarion.properties file.
If your Polarion license supports the Work Records feature, and if this feature is enabled in the project, an
administrator can configure values that represent Work Record types, and also whether or not the Type
and Comment fields of Work Records appear to end users as required fields. You can also configure a lock
date for Work Records to prevent any dated earlier from being modified.
In Work Records, the Type field is a drop-down list of values that define Work Record type. The values
appearing in the list are customizable in the work-record-type-enum.xml configuration file in both
global and project scopes. This file is accessible in the Enumerations topic ( Administration interface:
Navigation pane: Work Items Enumerations). You modify this configuration in the same was
as any other enumeration. For more information see Configure Enumerations.
This configuration is available in both global (repository) scope and project scopes. In both scopes, the
fields are not required by default and you need to create the necessary configuration to change that.
Configuration is performed entirely in the Administration interface of the portal — you do not need to edit
XML in a configuration file.
To change the default and cause the Type and Comment fields of Work Records to be required fields:
Procedure
1. Enter the Administration interface with permissions for the scope you wish to configure (global or
project).
2. In the Open Project or Project Group dialog box, select Repository if performing the configuration
in the global scope, or select the project you want to configure.
3. By default, no configuration exists and you will see Configuration does not exist yet in the
Configuration section together with the Create button. Click that button to create the configuration
for the selected scope. Two check boxes appear in the section: Type Required and Comment
Required.
4. To make the Type field required in Work Records, select the Type Required check box. To make the
Comment field required in Work Records, select the Comment Required check box.
5. Click the Save at the of the page to save your changes. If you decide not to save changes, navigate
away from the page by selecting a different topic in the Navigation pane.
If the Polarion license you are using enables Work Records, you can configure a locking date for Work
Records in each project. Work records dated on or before the locking date cannot be added, removed, or
updated for any Work Items in the project. This enables project managers to, in effect, close work record
reporting by teams as of the specified date. Note that this configuration may need to be changed fairly
often - monthly or even weekly. The principal Polarion administrator may find it easier to grant a project
manager or other user project administrator permissions so that this configuration task can be delegated.
Procedure
1. Log on with administrator permissions for the project that is to have the locking date set or modified.
2. Enter the Administration interface and select the project you want to configure in the Open Project
or Project Group dialog box. (See Access Projects).
3. If not already selected, select the Project topic in the Navigation pane. The project properties appear
in the Content Pane.
4. Specify a date in the Lock Work Records Date field. This field can be edited in place without clicking
the Edit button. When you hover your pointer above the field, you can invoke a calendar picker in
which you can select a date. The selected date is the date when Work Records in the project will be
locked.
5. After changing the date, click the Save button to effect the change.
By default, reporting of time values, such as Initial Estimate, or Time Spent , uses a fractional convention.
For example one half hour is reported as 1/2 h. It is possible to change reporting of hours to decimal
format (.50, 2.5 for example).
This requires a change to the system properties stored in the system properties file polarion.properties .
For information on this setting, see System Tuning for Advanced Administrators, property
useDecimalHoursDurationFormat.
You can configure the data columns that display in the Table view of the Work Items page. You can
customize the column display either globally or for a specific project. If you are not familiar with the basics
of the different scopes, you may want to review: The Administration Interface.
Note that individual users can reconfigure the Work Items table to suit their own needs and preference
via the Table Configuration dialog box available in the Polarion web interface. Their changes are saved to
their respective user profile. For information, see Customize the Work Items Table.
The Table customization is done by editing the table-settings.xml file for the scope you want to
customize, either online in the Table Configuration topic of Administration, or offline by downloading the
file from that topic, editing offline, and then uploading the modified file back to the Polarion server in the
same Administration topic.
The configuration file contains <column> tags for all the available data fields that can be displayed in the
Work Items Table. The tags for the columns that appear by default are uncommented. Other available tags
are placed inside a comment. If you want to remove one of the default columns so that it does not appear
in the Table, cut it and move it into the comment that contains the other available column tags. To make
one of the other available columns appear in the Table, cut its tag from the comment that contains the
other available columns and paste it into the block of uncommented column tags in the position you want
it to appear.
For example, if you wanted to add resolution as the third column in the table, cut the tag <column
id="resolution" ...> from the block of commented tags and paste it as the fifth tag in the block of
uncommented <column> tags.
3. In the Navigation pane, expand Work Items and select Table Configuration.
You can now download the relevant configuration file. If you are making a project configuration and no
configuration file for the project scope exists, you can use the controls in the Edit Project Configuration
section to create a project-scope copy of the global configuration file in the text editor, where you can
modify and save it.
Note
Administrators with global rights can optionally change the table configuration using the Table
Configuration dialog box as described in: Customize the Work Items Table. To change the global
configuration, be sure you have selected the Repository the Open Project or Project Group dialog box
before invoking the Table Configuration dialog box.
User queries on Work Items can sometimes find very large numbers of Work Items. However, it is not
likely that all of the items are actually needed. So for performance reasons, you may want to set a limit on
the number of Work Items that can be loaded in tables of Work Items.
You can do this with the system configuration property loadAllLimit (in the polarion.properties file.)
By default, the limit is 3000 Work Items.
Note that setting this limit in the configuration does not mean that is the number of items that is always
loaded. It reflects only the maximum number of items that are allowed to be loaded in the table. When the
number of items found by a query exceeds the configured limit, users are presented with a link Load first
NNNN where NNNN is the configured load limit. For example: Load first 3000. When a user clicks the link
to start the loading, items are loaded in blocks of 50. The count of loaded items is updated after each block
loads, so the user can estimate when the loading will be finished.
Note
The configured limit applies in Users, Roles, Projects, Time Points, Categories, Builds and Jobs in addition
to the Table view in the Work Items topic.
In a new, clean installation the fields available to display as table columns are listed in the configuration
file in comments. However, you may have an upgrade installation which has a version of the configuration
file without such comments. Therefore, it may be useful to have a complete list of fields that you can
optionally configure for display in the Work Items Table. The following table lists the field IDs of fields that
you can display as columns in the Work Items table, along with which ones are shown by default in new
installations.
linkedRevisions NO
comments NO
Note
Custom fields may also be used.
Configure queries
You can configure some named queries that can be entered in the Query field of the Work Items topic.
Users who do not know query syntax can simply enter the query name to run it.
This configuration is available for both Global (repository) and Project scope. If you are not familiar
with the basics of the different scopes, you may want to review: The Administration Interface. The
configuration is specified in the queries.xml configuration file, which contains comments and a
customization example.
Procedure
1. Log on with administrator permissions for the scope you want to configure (repository and/or
project).
(You can then customize it to suit your project. When you Save, a Project configuration
queries.xml link will appear at the top.)
5. You can edit a configuration file directly or download the Project and Global queries.xml links to
edit them offline.
6. If you edit a file offline, click Import from file to add it back to the Polarion repository.
The default global configuration contains several predefined named queries, each contained in a <query>
filter. The user-friendly name is specified in the name attribute. The Lucene query syntax, which will be run
when the user invokes the name in the Query field, is specified in the query attribute of the filter. The
following example query retrieves Work Items having no value specified in the Time Point field.
When users access the Work Items table in the Work Items topic, Polarion runs a default query that simply
queries for all unresolved Work Items: NOT HAS_VALUE:resolution. This default query applies to the
Repository and all projects.
Tip
This requires additional backend configuration. Contact your local partner or SaaS operations
representative for help.
Administrators can change this default query in the system property com.polarion.ui.defaultQuery
in the
polarion.properties system configuration file. The above query is the default value for this property, and
you can change it to any valid Lucene query that is preferred as the system default.
Users can override the query specified in this property by saving any query in the Visual Query Builder as
their personal default query for the Work Items Table.
The Working Calendar feature tracks the amount of actual working time available to projects. The Working
Calendar defines the working days comprising a normal work week, and working hours within each
normal working day. Exceptions to the normal working and nonworking days/times, including temporary
exceptions, can also be configured .
Working Calendar can be configured in 2 scopes: global (repository), and User. The global Working
Calendar, configured in the Administration interface, affects all Projects in the repository. In this scope it is
possible to allow for known nonworking time, such as national holidays, across the entire organization.
The User, or personal Working Calendar enables users to set vacations and other personal time off from
work, or fewer workdays or working hours in the case of part-time people. This configuration can be
performed either by an administrator, or by individual users.
The aggregate of both configuration scopes then affects the total capacity of each project. User calendars
affect only projects for which they have a role.
This topic describes the procedures for accessing and modifying the global Working Calendar, and for
accessing a user's Working Calendar for administrators working in the Administration interface. The user
calendar contains additional user interface controls. The modification procedure is the same whether the
user calendar is accessed by an administrator or by the individual user.
Note
• If you are not an administrator, and you want to update your personal Working Calendar, see
Configure your working calendar.
• Values for time are always rendered in server's time zone, regardless of the time zone where the user
is located. For example, if the server is located in the Eastern time zone of the United States, and
a user who is located in the Central Europe time zone updates a Work Item, the time stamp of the
update will be according to the server's time zone, not the user's time zone.
As an administrator you may need to know how to access the global Working Calendar, and a user's
Working Calendar in the Administration interface.
Procedure
Procedure
• Regular Schedule
• Schedule Exceptions
This section defines the normal work schedule for your organization (global scope) or a user (User scope).
In a new installation, the default settings are:
Days that have Start Time and End Time values are Working days. Days having no start/end time values
are Not-Working days.
Procedure
To quickly change a Working day (one with Start/End Time values specified) to a Not-Working day, you can
click the icon that appears to the right of the day. (Alternatively, you can just clear the values in the Start
Time and End Time fields.)
Tip
Click Revert to cancel the changes.
In the Schedule Exceptions section you can define exceptions to the regular schedule. Exceptions can be
permanent, or temporary for a specific period of time. For example, holidays that occur on the same date
every year can be set up as permanent exceptions to the normal work schedule. Holidays that fall on a
different date each year can be set up as temporary exceptions. Schedule Exceptions can be either of two
types:
• Time Off - the exception is time that will not be available for work in addition to any nonworking time
configured in the Regular Schedule.
Procedure
1. Enter a meaningful title for the exception in the Title field. For example: New Years Day Holiday.
2. Select the exception type by choosing a value in the Type drop-down list. For example: Time Off.
3. Specify the date when the schedule exception is to begin in the Date From field in this format:
yyyy-mm-dd. Alternatively, click the calendar icon next to the field and choose a date in the pop-up
calendar. For example: 2008-01-01.
4. If the exception you are defining is temporary, specify the date when it should end in the Date To
field, in the same format as mentioned in the previous step. For a one-day exception like our New
Years Day example, the value should be the same date as in the Date From field. If the exception is
ongoing, leave the Date To field empty.
5. If the exception you are defining occurs only on one specific weekday in the time period defined,
choose that day in the drop-down list in the Weekday column. Otherwise, leave the default value All
days.
6. If the exception you are defining is of the type Time Working, set appropriate time values in the Time
From and Time To fields, which are enabled when this type is selected. Time From is the time when
the additional working hours start, and Time To is the time when the additional working hours finish.
7. If you want to add another Schedule Exception, click the icon in the Actions column and repeat the
above steps on the new row that appears.
8. When you are finished defining any Schedule Exceptions, click Save in the Working Calendar toolbar.
To cancel all changes, click the Revert button.
Procedure
1. Click the in the Actions column of the exception you want to remove.
2. Click Save in the Working Calendar toolbar. To cancel the remove (before any Save), click Revert.
Tip
In a clustered server environment with multiple Polarion servers that host their own Polarion repository,
it is possible to link a Work Item hosted on one server's repository to another Work Item hosted on a
different server's repository. For more information, see Link to Remote Work Items.
You can configure Link Roles that define relationships between linked Work Items of the same type, or
different types. For example, the depends on Link Role can be specified for a link between Work Items
to indicate that the current Work Item depends on another Work Item. When you define a Link Role, you
must also define its opposite role.
Example
The depends on link role could have an opposite role is depended on by.
This link role is seen by users who view the linked item.
Link roles can be configured globally for the Repository of any Polarion server, and for individual
projects to customize the global configuration to the needs of the project. You can define as many link
roles as you need to establish the traceability you require. Project Templates may predefine project-scope
link roles.
Each link role definition can have one or more Rules, that control the types of Work Items that can be
linked to each link role. For example, a link role defined as verifies might have a rule that says that the link
role can only be applied from a Test Case to a Requirement.
Tip
Defining Rules for Link Roles is extremely important because they are reflected in the user interface
elements used to create links in Work Items. These Rules prevent users who may not understand the
various Link Roles, and the directionality of linking, from creating inappropriate links. (Links that would
result in erroneous traceability data in the system that is then reflected in dashboards and reports.)
Link roles are an enumeration defined in the Administration interface and their settings are stored in
the workitem-link-role-enum.xml file.
Procedure
1. Log on to the portal with administrator permissions for the scope you want to configure.
3. To configure the global scope,select Repository in the Open Project or Project Group dialog box.
To configure a project, select the Project to configure in the same dialog box. (See Access
Projects.)
a. If you are configuring link roles and rules on the Repository (global) scope, click Edit in
the Actions column.
b. If configuring link roles and rules for a Project, click Create New
The link role configuration table appears.
Tip
• Make sure the value of Opposite Name is meaningful. Look at the default global configuration
to see how the concept should work.
For example if you were to define a custom link role named amends, a logical opposite name
would be is amended by.
• ID, Name, and Opposite Name are required. Spaces are allowed in Name and Opposite Name.
• Do not use spaces in the ID and limit characters to ASCII upper and lower case letters, and
numbers, and underscore.
• You can create and edit opposite links for individual Work Items and during Bulk Edit.
• The Document Editor does not support Bulk Edit. If you would like to use it for Document-
contained items, switch to the Table view of Work Items.
Defines the parent-child hierarchy of linked Work Items for the following:
• The aggregation of Calculated field values.
(The aggregation of sum, multiply, average, min, and max values are always done based on
the parent-child hierarchy of linked Work Items defined by this checkbox.)
• When you move a Work Item with Parent selected from the tracker into a Document its child
Work Items are also moved.
10. (Optional) Enter Description that explains what the link role means.
11. Click in the Actions column
12. Click Save on the top left.
13. You should now go ahead and create some Link Role Rules.
You can edit existing Link Roles in the workitem-link-role-enum.xml file in Administration.
Tip
Need a Link Role for Reused or Branched Documents so Work Items link back to the original
Document?
Use a standard role like duplicates instead of system roles like branched or derived.
Procedure
1. Log on to the portal with administrator permissions for the scope you want to configure.
3. To configure the global scope,select Repository in the Open Project or Project Group dialog box.
To configure a project, select the Project to configure in the same dialog box. (See Access
Projects.)
The Rules for link role section of the Enumeration Designer is where you define rules for the link roles
you have defined.
Warning
New and modified rules are not applied to existing links between Work Items. If you had existing links
in your system that were created before Link Role Rules were configured, Polarion does not report any
errors if any of these preexisting links violate the newer Link Role Rules. The repository may contain
links which now violate Link Role Rules.
Procedure
1. Log on to the portal with administrator permissions for the scope you want to configure.
3. To configure the global scope, select Repository in the Open Project or Project Group dialog box.
To configure a project, select the Project to configure in the same dialog box. (See Access
Projects.)
Note
You can create a rule for links that go from a Work Item type in the current project to a Work Item
type defined in another project or group. To do that, select other in the To Types field and enter
the ID of the Work Item type in the desired project or group. A typical scenario for this is where,
for example, a Work Item type named Requirement is defined in the current project, and a type
named Test Case is defined in a different project.
7. Define your Link Role Rules and click Save on the top left.
Link Role Rules control the items reflected in the Action menu in the Work Item detail form in the
Work Items topic. Users creating links to other Work Items can only select valid Work Item types because,
thanks to the rule definitions, only types valid for the link role are presented in the menus.
The linking menus of Work Items can be configured to define menu items for creating new linking/linked
Work Items while working with an existing Work Item. Among other things, the role of created links can
be defined, so that when the end user creates a new Work Item using the menus, only links with correct
roles can be created.
The menus are located on the toolbar of the Work Item Editor pane in the Table view of the Work Items
topic.
1. Log on with administrator permissions for the scope you want to configure (repository or project).
2. To configure the global scope,select Repository in the Open Project or Project Group dialog box.
To configure a project, select the Project to configure in the same dialog box. (See Access
Projects.)
3. In Navigation, expand Work Items and select Form Menus. The Form Menus configuration
page loads in your browser.
At this point you can create a new configuration for Linked Work Item Menus and Linking Work Item
Menus, or update or delete existing configurations, if any.
When Creating a new configuration, you select the Interface in which the configured menu appears, and
the type of Work Item that can have the menu item. Unspecific means the menu item is available for any
type.
Menu configuration is done using XML in an online editor. For new configurations, an example is provided
in comments. Some help is embedded on the menu configuration pages.
Reference information for this configuration is provided in embedded Quick Help on the administration
pages in the portal.
Tip
You can configure a query under the Form Menus administration page for Projects to be returned while
linking Work Items using the Linked/Linking menu. Use the projectQuery to set up the query.
The following example shows the basic structure of a linked/linking menu configuration file for a View:
Example
The <item> tag can take the following attributes. At least one of the label, role, type, or
childInDocument attributes must be defined.
Attri
bute Description
labe Defines the label of the menu item. If it is not defined, and childInDocument=true is set, then
l the label is "Child in Document". Otherwise, the labels of the objects defined by other parameters
are as [role], [type] in [project]/[document].
role Defines the Work Item link role to be used. When role is not defined, type is defined, and more
than one link role is allowed by link role rules for the type, then this item opens a submenu that
lists the roles allowed by the link role rules. When only one role is allowed for the type, the item
creates a new Work Item directly.
type Defines the Work Item type to be used. When not defined, role is defined, and more than one
type is allowed by link role rules for the role, then this item opens a submenu that lists the types
allowed by the link role rules. When only one type is allowed for the role, the item creates a new
Work Item directly.
proj This configuration defines a Lucene query for projects. This item then opens a submenu
ectQ populated by the results of the query, and the chosen project is used in the Work Item Picker.
uery The role and type attributes must be specified as well, otherwise this attribute is ignored.
="lu
cene
Quer
y"
Note
Projects that the user does not have read access to are filtered out from the submenu. If the query does
not return any results, the parent item is not displayed in the menu. If the query only returns one project,
no submenu appears and that project is selected automatically after clicking the menu item.
The following attributes can be used when creating a new Work Item with a link:
Attribute Description
project Defines in which project a new linked/linking Work Item will be created. When not
defined, it will be created in the current project. The value is the ID of the target project.
document Defines in which Document a new linked/linking Work Item will be created. Use the
project attribute to specify the project containing the Document.
inSameCont Defines that the linked/linking Work Item has to be created in the same container (for
ainer="tru example Document). When set to true and the container (document) does not allow
e" creating the defined type or role, then this <item> does not appear in the menu.
childInDoc This attribute can only be used in the create-linking-menu.xml file. It defines a menu
ument="tru item to create a child Work Item in the Document specified in document. This item is
e" only displayed when the current Work Item (the one the user is currently viewing and
from which the user is invoking a new linked/linking Work Item) is in a Document.
titlePrefi Defines a prefix for the title of the new linked/linking Work Item. When specified, even
x as an empty string, then the new linked/linking Work Item contains the value specified
in titlePrefix plus the title of the original Work Item. This attribute can be used
together with titleSuffix.
titleSuffi Defines a suffix for the title of the new linked/linking Work Item. When specified, even as
x an empty string, then the new linked/linking Work Item contains the title of the original
Work Item plus the value specified in titleSuffix. This attribute can be used together
with titlePrefix.
copyFields A comma-separated list of fields (for example field IDs) to be copied from the original
Work Item to the new linked/linking Work Item. If also specified, then attributes
titlePrefix and/or titleSuffix override copyFields if copyFields specifies
the title field.
Set the following attributes under Navigation Work Items and select Form Menus:
Attribute Description
existing="true" Add the existing="true" attribute to a line to
avoid creating a new item. If this attribute is not set
in the configuration, the default setting is false.
query="luceneQuery" This configuration inserts any valid Lucene query,
which is transformed into bubbles in the Work
Item Picker.
project="projectId" This configuration gives you the option to list items
from a different project in the Work Item Picker.
This configuration also sets the Scope of the query
to "in Project".
scope="repository/project/document" This configuration sets the Scope of the Work Item
Picker.
All attributes used for the configuration of the Form Menus can be used in this configuration, too (like
label, role, and so on).
• If the Work Item is in a document, the default Scope setting is "in Document".
• By default, the Scope setting is set to "in Project".
If the project attribute is configured, then Scope is automatically set to "in Project".
If a scope is configured together with the project attribute (which is not recommended) as "in Repository",
then the scope is set to "in Repository", which returns the same set of items as if the scope was set to "in
Project".
If the scope is set to "in Document", the scope in the Work Item Picker is set to "in Project", as the
combination of project and document is not valid.
Note
The scope parameter is set up so that users can only select values from a drop-down menu in the Work
Item Picker. If a user tries to configure Form Menus (on a repository level) to show a specific type of
Work Item which is not defined in the actual project in which users want to add the link, then that type
of Work Item is not listed as an option.
When you are linking existing Work Items, the title of the Work Item Picker displays the role that you are
linking the Work Items with.
Example
In the above example, in the linked menu under the separator, two items are shown. The first one has the
Existing related label without an icon, but with an arrow expanding to a submenu listing all the relevant
Work Item types. Selecting any of the items opens a Work Item Picker prefiltered to the selected type. The
second item in the Linked menu has the Existing related task label with the Task icon. Selecting it opens
a Work Item Picker with the Scope set to in Repository and the Type: Task and Initial Estimate: Any and
Unresolved query bubbles.
Example
tracker/requirement-create-linking-menu.xml:
<menu>
...
<separator/>
In the above example, in the linking menu under the separator, one item has the Existing implemented
Issue label and the Issue icon. Selecting it opens a Work Item Picker with the Scope set to in Project and
the Type: Issue and Project ID: drivepilot query bubbles. The second item in the Linking menu has the
Existing related Task from projects label with a Task icon. An arrow expands to a submenu listing all the
projects found by the project query. Selecting any of the items opens a Work Item Picker prefiltered to the
selected project.
End users can link Work Items with an applicable Link Role or its opposite, so as not to have to switch
between different Work Items in order to link with the desired relationship. When adding backlinks,
the Role list shows forward link roles first, followed by appropriately filtered backlink roles from the
current project. If the picker dialog box is used, it presets the correct query based on the current project's
configuration.
Opposite links can be created or deleted in an individual Work Item or by using Bulk Edit.
You can configure the default state of the Suspect attribute of Work Items.
This configuration is available for both the global (repository) and project scopes. If you are not familiar
with the basics of the different scopes, you may want to review the topic The Administration Interface.
Procedure
1. Log on with administrator permissions for the scope you want to configure (repository and/or
Project).
2. Enter the Administration interface and open the repository, or the project you want to configure.
See Access Projects.
3. In the Navigation, expand the Work Items node and select Linking. The Linking administration
page appears.
4. Select Auto-Suspect to automatically set all linking that comes from child Work Items as Suspect.
If you do not want the Suspect flag set automatically on new and modified Work Items, do not
select this item.
What it changes:
• The default Save button in a Work Item preview and the Work Item table (in both Table and
Tree view) changes to Save and Suspect.
( Save and Suspect automatically sets all links coming from child Work Items as Suspect.)
• The Save button on a Work Item preview when you create a new Work Item is also changed to
Save and Suspect.
When users create a Work Item with linked child Work Items it marks any links to them as
Suspect.
5. Click Save to save your changes.
What to do next
Remember that projects inherit the global configuration. If you want to override the global Auto-suspect
setting for a project, click the Create button on the Linking page toolbar when you are working in a
project, then set the options as you want them for the project. If you want to revert from an existing
project configuration back to the global repository configuration, click the Delete button to delete the
project-scope configuration.
Configure Auto-assignment
Auto-assignment is an important feature that can save many hours of work over time. It is recommended
that you take the time to become familiar with it, and then set up a default configuration for your
system, and specific configurations for projects based on the their individual characteristics. You can
configure Polarion to automatically assign new or existing Work Items to one or more users based on
some condition(s). For this feature to work, set the Assignee(s) field to Automatic manually after you
created a new Auto-assignment rule, and save the Work Item again to properly execute it against the
new rule. You have to do the same steps when a Work Item is duplicated (where no user is assigned to the
source Work Item but the duplicated Work Item meets the criteria of the Auto-assignment rule).
You can configure one or more Auto-assignment Rules which specify the conditions a Work Item must
meet in order for it to be automatically assigned, and the user or users to which it is assigned if the
conditions are met. Rules can be defined which apply to all Work Item types, or to one specific type.
For example, you might define a rule that says any type of Work Item having a value of usability in the
Categories field is automatically assigned to one or more users who are responsible for usability issues.
You can optionally select Current User to have new items assigned to the currently logged-in user. By
default, Current Assignee would be applied only if the user is among the possible assignees for the
current context. You might want to constrain this further with one or more rule conditions.
Caution
Use a Workflow Function if you want Assignee(s) to automatically change when the Status does. (Not
Auto-assignment bound to a Status value.)
Auto-assignment is not active by default. This configuration is available for both global (repository) and
Project scope. If you are not familiar with the basics of the different scopes, you may want to review
Administration Basics: The Administration Interface.
Procedure
1. Log on with administrator permissions for the scope you want to configure (repository or project).
2. Enter Administration.
3. If making a global configuration, select Repository in the Open Project or Project Group dialog box.
If making a project configuration, navigate to and select the Project in the Open Project or Project
Group dialog box.
(See Access Projects.)
4. In the Navigation pane, expand the Work Items node and select Auto-assignment.
The Auto-assignment page displays a table of the existing auto-assignment rules, if any.
• Access the configuration in the desired scope, as described in the previous section.
• If no rules exist for the current scope, click the Add New Rule button to add an auto-assignment rule. If
one or more rules exist, click the Add Rule Below in the row below which the new rule should appear in
the table of rules. (Rules are processed in the order listed in the table).
You can modify existing rules in either the repository or project configuration. A common reason for
changing a rule is that the assignee(s) need to be changed due to changes in personnel, responsibilities,
etc.
Procedure
1. Access the Auto-assignment topic in Administration as described earlier. Be sure you have opened it
in the scope you want to configure.
2. In the table of existing Auto-assignment rules, click the Edit button. The Auto-assignment
Configuration page loads.
3. Edit the Conditions and or Assignees as needed.
4. Click the Save button. If you want to create or edit another rule, click the link Return to Auto-
assignment.
Remove a rule
Procedure
1. Access the Auto-assignment topic in Administration as described earlier. Be sure you have opened it
in the scope you want to configure.
2. In the table of existing Auto-assignment rules, click the Remove button and respond to the
confirmation prompt.
Warning
If you have administration permissions for the Repository, be sure you are removing a rule in the correct
scope. For example, don't remove a rule in the Repository scope thinking you are doing so for a project.
Configure Voting
This configuration is available for both global (Repository) and project scope. If you are not familiar with
the basics of the different scopes, you may want to review The Administration Interface. Configuration
data is stored in the voting.xml configuration file, which contains comments that explain the XML
elements and their usage.
Procedure
1. Log on with administrator permissions for the scope you want to configure (repository and/or
project).
2. Enter Administration.
3. To configure in the global scope, select Repository in the Open Project or Project Group dialog
box. To configure a specific project, navigate to and select the project in the Open Project or Project
Group dialog box.
(See: Access Projects.)
4. In the Navigation pane, expand the Work Items node and select Voting.
5. Use the appropriate link in the Configuration section to download the configuration file to your local
system, or edit online with the text editor provided.
6. If you edit the file offline, use Import from file to upload the modified file back to the Polarion
repository.
An administrator can configure Polarion to support multiple human language translations of Work Items.
When correctly configured, a Title and Description field for one or more additional languages appear in
the Work Item Editor in Tracker views, and users can switch languages in Documents to view translated
Work Items.
The default behavior for Polarion search lets users perform any query against all the content of the Lucene
or SQL indexes. The search returns the list of object URIs that match the search, regardless of whether or
not the user has permission to read those artifacts.
Users can determine the unique ID of a found object and the Project where it resides. The user's
permissions get evaluated when they attempt to access the artifact. The API denies them access if they do
not have permission to READ the found object.
If this level of search security is insufficient, you can also restrict search capabilities to reflect per-field
configurations for Work Items.
This prevents global user roles from running queries for fields they do not have permission to view.
Caution
This additional security feature has significant performance implications, so choose wisely between
enforcing the more strict search security and providing a good user experience and performance for your
end users.
You can manage access to application data by limiting the search results of users who belong to a specific
user role.
(You can revoke user permissions to read a Work Item field and restrict their use in queries so that
restricted users cannot speculate on the content of fields they are not entitled to read.)
To enable this feature, specify the set of global roles with restricted privileges in the following property
in the polarion.properties file:
• com.siemens.polarion.security.permission.globalRolesWithQueryFieldRestrictio
n
Once set, Polarion administrators can revoke individual read permission to either built-in or custom fields in
Administration at:
Once configured, any Lucene query users belonging to the restricted global roles are pre-processed and
checked against user permissions before execution.
Queries that contain restricted fields are blocked, and do not appear in the search results.
Example
Restricting a field named secret in project A does not affect another field called secret in project B.
• However, due to potential ambiguities on the global scope, all fields sharing the same ID as a
restricted field within a different project are blocked in a query regardless of their relationship.
• The query builders only provide fields that a user can read and hide the fields that they cannot.
So, it's possible to create a Custom Set that grants permission to a subset of users to read the value of
a Work Item field even if a general permission/query restriction is set. (But the search capabilities of the
restricted fields are disabled for everyone).
Note
Custom Sets do not work the other way around:
If a Project's most generic permissions (Other Work Items) are set to allow users to READ, but a
Custom Set denies them the right to READ, the search would still work as usual.
(It would be too restrictive, and no search context is provided on this API level.)
Searching via a particular field can also be prevented globally via the following property:
com.siemens.polarion.security.permission.globalRolesWithQueryFieldRestriction.
The property also prevents the restricted fields from being indexed in fulltext queries.
(The same definition of fields is used as the list of field suffixes that cannot be used in SQL queries and
fields that are excluded from a Lucene full-text search. All SQL queries containing a field that equals to or
ends with one of the listed suffixes will be blocked.
Note
The SQL search restriction is not enforced in LiveReports and Pages, so any user allowed to edit
LiveReports (including the My Polarion personal dashboard) can freely execute SQL queries without
restrictions.
Configure Collections
Related Topics
What is a Collection?
Create/Delete a Collection
Add/Remove Collection Documents
Work with Collections
Work in Collections
Collection Baselines
Reuse Collections
Close/Reopen a Collection
Configure Collections
Here's where you can configure Collections to appear in Navigation, set up Collection permissions, add
Custom Fields and allow links that are outside the Collection context.
To get Collections to appear in Navigation, you have to configure permissions and add the following
to your project's Topic configuration.
<topic id="collections"/>
Caution
To create Collections, you must grant both the CREATE NEW and MODIFY permissions.
Tip
You can also create a Custom Set of permissions for Collections.
• In the example above, a user assigned this permission set would not be able to reopen a Closed
Collection.
• If the in the MODIFY permission for say, the project_admin role, was replaced with then
only project_admin users could reopen a Closed Collection.
For Polarion 2404+ installations, the default permissions for Collections are already defined in the
permimission.xml file for both demo and non-demo projects.
Warning
When Polarion is updated, all global and project-level Collection permissions must be redefined by
admins.
SVN Permissions:
Procedure
1. For new (clean) installations of all demo projects and project templates for Collections.
(.polarion/collection/instances), SVN access is allowed and permissions are granted (if not
inherited):
• project_admin, project_assignable = rw;
• project_user = r
2. The same goes for new projects created after a Polarion update.
(Only when created based on built-in templates, otherwise see 3.)
3. For custom project templates, administrators must manually define SVN access for existing projects.
It should be set for the folder .polarion/collection/instances, but it doesn't exist until a
Collection is created.
Administrators with the MODIFY permission can add a Custom Fields section with one or more Custom
Fields to the Collection detail screen.
Procedure
Tip
You can make the field mandatory by selecting the Required checkbox.
4. (Optional) Enter a Description. It appears as a tooltip when users hover over the Custom Field's
name.
Added Custom Fields appear in a new Custom Field section in all of your Collections.
By default, links that lead outside a Collection are not visible in the Collection context.
Tip
For reference information on the above properties, please obtain the Polarion System Configuration
Properties Reference, a PDF document available on the Documentation page of the Polarion product
center on Support Center.
Configure Testing
Administrators can configure Test Management features both globally for the repository to create a default
configuration, and in any project to override global defaults and create a custom configuration for the
project.
This configuration specifies mapping of test cases to a configured Work Item type, parameters for
automated testing, and how Polarion imports results of external testing tools. It also specifies the values
for several enumerations which appear in various lists in different configuration fields. You can configure:
1. Log on with administrator permissions for the scope you want to configure (repository/global or
project).
2. Enter Administration if you are not already in it after you log on.
3. Open the repository or project you wish to configure. (See Access Projects.)
4. In Navigation, expand the Testing node to expose the testing configuration topics.
Related Topics
Before performing the main testing configuration, you should review the settings in the enumeration
topics and make any changes. The values you specify in these topics are used in lists in the main testing
configuration topic.
Test results
The Test Results topic enables you to specify a set of values (called an enumeration) that define different
outcomes or results of testing. For example, you specify if the result of a Test Run that passes should be
labeled Passed, or Succeeded, or something else. You should define a value for every possible result of
your testing process. An example of a set of such values might be something like the following:
You can specify an existing icon for any value, or upload a custom icon by clicking the Select button on the
relevant row.
The Create Defect column, if selected, means that a Work Item representing a defect will be created when
a Test Run finishes running and terminates with the result defined on the row. For example, you would
probably select this option for a Test Result representing test failure.
You can add a new Test Result value to the table by filling in the last row. You can add more Test Result
values to the table by adding a new empty row by clicking the icon. You can remove a Test Result value
by clicking the icon on the relevant row.
Tip
Left click on and keep the mouse button pressed to drag your items into the order that you want
them.
Be sure to click Save when finished, before navigating to some other topic.
This topic enables you to define custom fields which should be added to Test Runs to store information
from external testing tool results or manual testing results. For example, if your tool returns a datum error
code that you want to track in testing results, you can add a custom field named. for example, Error Code.
You can add as many fields as are needed, one field per row of the table. Add more rows using the icon.
The Multi field, when selected, enables multiple values to be entered into the field. This option is only
enabled when the field type selected in Type supports multiple values.
The Require field, if selected, means that the field is required and changes to the Test Run cannot be saved
unless a value is supplied. This is more applicable when Test Runs are run manually, or when results of
automated tests are logged manually.
You can define custom fields to add to Test Records that store information from external or manual
testing tool results. For example, if your tool returns a datum error code that you want to track in test
record results, you can add a custom field named Error Code.
Tip
You can Query for Test Records by their custom fields.
• Custom field editors are available when you execute a Test Run.
• Custom field values are visible in Test Record tables, widgets, and macros.
Procedure
(If selected, users must enter a value for the field and cannot save the Test Record without one.)
This topic enables you to define the different status values that Test Runs can have, including a standard or
custom icon image to represent the status value in the user interface.
The Terminal option marks that the status is a terminal one, meaning that testing activity is complete. If
you set a Test Run to a status marked Terminal, the Finished on field's value is automatically filled in with
the current date-time.
This topic enables you to specify values that define the type of a new Test Run. Typical values include
Manual and Automatic. You can change the semantics or add more values to cover all the types of Test
Runs you need to create to support your testing process. You can optionally require that users provide an
electronic signature after running Test Runs of any or all of the configured types.
Tip
Left click on and keep the mouse button pressed to drag your items into the order that you want
them.
Help text at the bottom of the Configuration page. This configuration is available in the Global (repository)
scope, and in projects. Project settings override the global settings.
• Test Cases: These are instances of a configured Work Item type which define a specific test or set of test
steps. Test case items can be linked — to the requirement type item(s) they verify, for example. For test
management purposes, the global configuration and each project configuration should define a Work
Item type for test cases. Some Polarion project templates are preconfigured to provide a type named
Test Case.
In project templates (and projects based on them) the Test Case type is the type for automated tests. It
is used to define the link roles and custom fields. The assumption is that all the test-case-like types have
the same custom fields used in the testing configuration and the same link role type between a Defect
and Test Case.
You may need to define other Work Item types for different types of test cases: acceptance test case,
functional test case, etc.
You can do this globally or in any project in Administration Work Items Enumerations
workitem-type-enum.xml.
• Test Runs: These system objects represent an instance of running or performing one or more test cases,
and the result of that process — test(s) passed, failed, or blocked.
Polarion project templates for test management projects is preconfigured to include the Test Run type.
• Defects: These Work Items record and describe a defect. Defects may be created as the result of a Test
Run, either manually by testers performing tests manually, or automatically by a test result import job
configured to import the results of external automated tests. For test management purposes, the global
configuration and each project should define a Work Item type to represent defects.
Tip
Most Polarion project templates are preconfigured to provide a type named Defect or Issue.
The Testing Configuration page contains settings that specify a number of properties for Test Runs:
• You need to specify which configured Work Item type Test Runs should link to as test cases. For example,
a global configuration might contain several Work Items types that are analogous to different types of
test cases that are run in different types of projects. A project configuration needs to specify which type
should be used by project Test Runs.
• You can specify templates for several purposes including default for Test Runs, and Work Items
representing test cases and defects. Generally, you select an existing Test Run, test case item, or defect
item to serve as the template for others that are created during the testing process.
• You can specify how Test Runs map passed tests, failed tests, and errors to specified values in the Test
Results enumeration.
• Defects are created as a result of failed tests. You can specify properties of such defects including
which Work Item type to create to represent a defect, the link role between defect items and Test case
items, field values from test cases and Test Runs to be copied to defect items, and more. Again, refer to
the embedded Quick Help text at the bottom of the configuration page for details.
Note
The values from the Test Run, Test Case, and Test Case Verdict fields are hardcoded so that they
automatically appear in the Description field of all Defects generated by failed Test Cases.
Note
This toolbar button is present only if the system configuration property
com.polarion.hideMigrationTestStepsButton is set to false in the polarion.properties file.
In earlier implementations of the Test Steps feature, manual test steps were created and stored in the
Description field of Work Items. In later implementations (beginning with version 2012-SR3) test steps are
created and stored in a dedicated custom field of type Test Steps. The Migrate Test Steps button enables
an administrator to move existing test steps data from the Description field to the new Test Steps field of
Work Items. Migration is available only in the project scope and is performed on Work Items of the type
specified by the administrator in the Migrate Test Steps dialog box. (This would normally be the Test Case
type.)
Before running the migration utility in a project having existing Test Steps data in Description fields, you
must create a corresponding Test Steps configuration in ( Administration Testing Test
Steps). Names of the Test Step Columns in the configuration must be the same as the column labels in
existing Test Steps tables (in the Description field of Work Items). You must also configure a custom field of
type Test Steps for the Test Case type Work Item. For complete information please download the Polarion
Test Steps Migration Guide.
Automated testing
This topic defines parameters used for importing results of automated tests (thereby enabling tracking of
those results).
Defines which of the configured Work Item types corresponds to a test case.
Defines which Test Run to use as a template for creating new Test Runs when importing results of
automated tests. (May be overridden in a job or build configuration.) Enter the ID of an existing Test Run
from the current project.
Defines which Work Item to use as a template for creating new Test Case Work Items while importing
results of automated tests. (May be overridden in job or build configuration.) Enter the ID of a Work Item
from current project or projectID/workItemID for Work Items from other project.
Defines which string-type Custom Field (of Test Case type Work Items) to use for storing the ID string of an
automated test, the results of which are being imported. It is needed for subsequent imports of the tests in
order to recognize Test Case type Work Items created by previous import(s). The value for Java JUnit tests is
the name of a specific test class and method.
(Work Item Types are configured in Administration Work Items Custom Fields.)
Defines the conditions under which a single defect Work Item, referred to as a summary defect, is created
and linked to a Test Run instead of multiple defect items, one for each failed Test Case. It is useful for
situations when automated tests fail because of some environmental problem not directly related to the
concrete Test Cases, which causes many test failures.
This section allows mapping of automated test results to configured Test Record Result and Test Run Status
values in Polarion.
This configuration also specifies for which Test Result(s) a linked Defect item should be created.
Before configuring this mapping, you need to configure the two enumerations: Test Run Statuses and Test
Results, in the corresponding administration topics under Testing.
Note
When there are multiple types of test results, the Test Run status will be mapped as follows:
• If there are any failures (and no errors), the Failed status will be set.
• Otherwise, the Passed status will be set.
Manual testing
This topic provides options and settings for manual testing and Manual type Test Runs.
Here, you can specify a Lucene query to retrieve a subset of all Work Items when users manually select
Test Cases for a Test Run.
Examples:
The query limits the number of items in the Work Items table to a reasonable starting point before
manually selecting Test Cases for a manual Test Run.
Tip
• You are not restricted to the query results when selecting Test Cases manually and can construct and
run any query in the Work Items Table view at any time while selecting Test Cases.
• If you select Test Cases outside the scope of the default query results, you are warned and prompted
to confirm your selection.
Click Select Test Cases in the Actions menu of a Test Run to select Test Cases for it.
(If the Select Test Cases field is set to Manually, By Query on Create, or From LiveDoc on
Create.)
Note
You can only use Select Test Cases in a Test Run Template if the Select Test Cases field is set to
Manually.
Defines whether re-running and correcting of manually executed Test Cases is allowed.
Defect configuration
Administrators can configure how and when defects are automatically created when a Test Case fails in a
Test Run.
Defines the project in which Defects (resulting from failed tests) should be created.
Tip
For more information on how to enable or disable defect generation, see Test results.
Defect Type
Defines which of the configured Work Item types is used to represent Defects resulting from test
failures.
Defect Template
Defines which Work Item is used as a template for creating a new Defect type Work Item as a result of
test failure while importing results of automated tests, or when a manual Test Case is performed. It is also
used as the template for the Summary Defect). Enter the ID of a Work Item from the current project
or the project ID and Work Item ID for Work Items from a different project, in this format: projectID/
workItemID.
Link Role
Defines which Link Role is used for linking Defect Work Items (created when test results contain failed
tests) to Test Case Work Items.
Reuse Defects
Defines when the Defect created when a Test Case fails is reused.
Never:
When set to Never, if the current Test Record does not have a linked defect, a new defect is always created.
While retesting, the defect that is already linked to the test record can be reused.
1. First If failed in group and If failed in previous check iterations of the Test Case in the current Test
Run. If there is a resolvable, unresolved, not summary defect, it is reused.
2. Then they check Test Runs with the same Group as the current Test Run and in the same Project as
the current Test Run. If there is a resolvable, unresolved, not summary defect, then it is reused.
3. Then, the if failed in previous strategy checks Test Runs in the previous group and in the same
project as the current test run. (The previous group is determined by searching last Test Run by
creation time with a different group.) If there is a resolvable, unresolved, not summary defect, then it
is reused.
4. Otherwise no defect is reused.
Always:
1. Always finds the top 20 Test Records in the Project of the current Test Run, for the same Test Case
that have a defect set.
(Sorted by execution time in descending order.)
2. It then iterates over these defects and finds the first one that is resolvable and not a summary defect
of its Test Run.
3. If such a defect is found and has no resolution, it is reused.
4. Otherwise no defect is reused.
Perform Auto-assignment
Defines if auto-assignment should automatically fill the Assignee field in new Defect items created
automatically for a failed Test Case.
Defines whether re-running and correcting of manually executed Test Cases is allowed.
Defines which fields are copied from the Test Case Work Item to automatically created Defect Work Item(s).
Note
The values from the Test Run, Test Case, and Test Case Verdict fields are hardcoded so that they
automatically appear in the Description field of all Defects generated by failed Test Cases.
Defines which fields are copied from Test Run to an automatically created Defect Work Item. When the
source field is single-enum type field and the target is multi-enum type field, then the value is added,
otherwise the value in the target field is overwritten.
When To Existing is selected, then this mapping is also used when an existing defect item is linked to new
failed Test Record.
There is a job polarion.jobs.testruns.delete that can be run to clean up old Test Runs. The job
runs in the global scope, but it uses configurations from project scopes.
Note
Enabling this option in the global configuration enables it in all projects that do not define their
own configuration for automated cleanup of old Test Runs. Test Runs in such projects will be deleted
according to the settings in the global configuration, which may or may not be what is wanted. It is
advisable make sure that projects subject to regulatory compliance are configured so that no Test Runs
that are important for regulatory reporting are deleted.
You can optionally define a Lucene query in the field Query used by job to select Test Runs for deletion,
that returns the set of Test Runs to be deleted by the job. This filtering query is automatically extended by
Polarion so that the job never deletes Test Run templates and Test Runs that have the Keep In History flag
set.
When Test Runs are deleted by the job, no email notifications are generated, and nothing is shown in the
Activity stream.
Example query
Polarion provides the following macros which can be used to incorporate export-import functionality into
Test Run pages:
1. {export-tests} - Renders a link which launches a dialog box enabling a user to export of a set of
Test Cases to Microsoft Excel. Use the query to retrieve the test cases to be exported. Example:
{export-tests:query=status:active|sortby=id}
Excel round-trip export prefers the current context's export template when searching for a default
one. (It takes first export template in lexicographical order from the project configuration, then the
first in lexicographical order from the global configuration.)
2. {import-test-results} - Renders a link which launches a dialog box enabling a user to import a
Microsoft Excel file containing test results.
For complete syntax information, see the Syntax Help provided when editing a Test Run page.
You can configure any Test Run Template to add a prefix at the beginning of the IDs of new Test Runs
created from the template. The specified prefix will be added to both manually specified and generated
Test Run IDs.
Procedure
1. Review the Test Run Templates, and decide which of them you want to have add a prefix to new Test
Run IDs.
2. In each template you choose, edit the template Properties and enter a prefix value in the Test Run ID
Prefix field.
For example, in a template named Software Design Verification Test, you might specify a prefix like
SWDVT, or SDV.
When manually creating a Test Run, users can select the Test Run Template. If an ID prefix is configured in
the template, and the project is not configured to generate Test Run IDs automatically, the prefix is shown
as read-only in the Create Test Run dialog box, before the text box in the ID field.
You can set up the testing configuration to automatically assign IDs to new Test Runs.
When configured, users who manually create new Test Runs do not need to specify an ID, and the naming
convention will be consistent for all Test Run IDs.
Procedure
Generated ID Format
The ID of new Test Runs will begin with the value configured in the Test Run ID Prefix field of the Test
Run Template (if one has been specified), followed by a dash (-), followed by a unique ID generated by the
system. This ID has the following form:
PREFIX-YYYYMMDD-HHMM with a uniqueness suffix (generated only if necessary) in the form of _NUM
When users manually create a new Test Run, if generated IDs are configured, the ID field is hidden in the
Create Test Run dialog box. The generated ID appears in the new Test Run after it is created, and the ID
cannot be changed.
The first time you import automated test cases (jUnit tests, for example) to Polarion, it is unlikely that you
would want notifications sent about newly created Test Case type Work Items. Also, it is probably not
necessary to show all the resulting Create activities in the Activity Stream. This is especially true if you are
importing a large number of test cases.
An automated test case is a Work Item of the type configured as Test Case, with a nonempty value in the
custom field defined as the Test Case ID (see configuration page in Administration Testing).
There is a system property that defines a threshold above which notifications are not sent, and the Activity
Stream is not updated when new automated test case Work Items are created. The default value is 50,
meaning that if more than 50 new Test Case items are created, notifications and activity are not triggered.
Procedure
1. Using any text editor, open the system properties file polarion.properties (follow link for location).
• If [VALUE] is positive, notifications and activity streaming will be suppressed if the number of imported
automated tests exceeds [VALUE].
• If [VALUE] is 0 (zero), no notifications will be sent and no activity will be streamed regardless of the
number of automated tests imported.
• If [VALUE] is negative, no threshold is applied and all notifications are sent and all activity is streamed.
Warning
Setting no threshold can result in significant temporary performance degradation of Polarion, your SMTP
server, and your network if large numbers of automated tests are imported and no threshold limit is set,
to say nothing of user irritation if large numbers of notification emails arrive in their in-boxes as a result
of some test case import.
If you have very large manual Test Runs, the default system configuration can result in excessive
numbers of Test Run records in the historical database. In such cases, a System Administrator can set
a system property to reduce the number of records generated. See Prevent excessive Test Run recordsfor
information.
Polarion can support formal testing review and sign-off process for Test Runs, using secure electronic
signatures compliant with U.S. 21 CFR Part 11. An administrator can map the organization's review and
sign-off process to the Test Run Workflow configuration. Each step in the process can optionally be set up
to require an electronic signature before a Test Run can move to the next stage in the workflow
If you have updated an existing Polarion system from a previous version that did not support workflow for
Test Runs (version 2015 or earlier), you will need to enable the feature in Administration before it can be
used with existing projects. This section provides details about the procedure.
You should enable Test Run workflow in project configurations first, then in the global scope. This ensures
that existing projects do not inherit the global configuration incorrectly. For example, some projects might
have Status definitions that are incompatible with the initial global workflow configuration. During the
setup process, Polarion creates an initial workflow configuration for all Test Run types in the scope based
on the current configuration of Test Run statuses.
Warning
Polarion does not support having some Test Run types with workflow, and some types without workflow
in the same project. Polarion sets up a default workflow configuration applicable to all Test Run types,
which can be overridden by defining workflow for specific types. To avoid problems, do not remove the
All Types workflow configuration in any scope. You can modify it to be as generic or a broad as you
want, and then focus on type-specific configurations.
Procedure
1. In project Administration's Navigation, expand Testing and select Test Run Statuses.
(Only present if the workflow feature is not already set up.)
2. If you need to modify the Statuses configuration, do that now. You can still make changes after Test
Run workflow is enabled. However, the initial setup is based on the current statuses, so it is preferable
to fully define all the Test Run statuses the project needs before proceeding.
3. On the toolbar of the Test Runs Statuses topic, click Set Up Workflow.
4. Follow the messages in the dialog to complete the setup operation.
Procedure
2. Enter global Administration, and in Navigation expand Testing and select Test Run Statuses
(only present if the workflow feature is not already set up).
3. On the toolbar of the Test Runs Statuses topic, click the Set Up Workflow button.
4. Follow the messages in the dialog to complete the setup operation.
After the setup is complete, the Test Run Statuses node in Navigation becomes hidden, and is replaced
with the Test Run Workflow node, and the Test Run Workflow page opens. On this page you can view
and edit the default workflow configuration that Polarion created for all Test Run types, and you can define
type-specific workflow for any of the existing Test Run types, which appear listed in the table. If you need
to define new types, you can do so.
You will get a simple all-allowed workflow upon using the Set Up Workflow action described above. You
can optionally install the new default from a project template instead, either by picking it up from a
new project created from a corresponding template, or by mining it directly from the plugins and then
uploading it to your own project's Subversion repository.
If you have previously configured workflow for Work Items or Documents, you already know most of what
you need to be able to configure it for Test Runs. As with these other workflows.
• In the Statuses section you define every status a Test Run in the scope can potentially have during its
lifecycle.
• In the Actions section, you define the actions that users invoke to trigger the transition of a Test Run
from one Status to a different Status. This is where you, in essence, map your specific process for
running tests into Polarion's workflow control.
Programmatic workflow functions can be specified and their input parameter values configured.
The configured workflow functions are then executed along with the respective transition actions.
The execution can be conditional, dependent upon one or more specified workflow Conditions. All
conditions must be satisfied in order for the related function to be executed.
• In the Transitions section, for each Status in the left column you specify to which other Statuses it can
transition, and which of the defined Actions triggers each transition.
A brief example can help to grasp the concept. Suppose there are only 3 possible Statuses a Test Run can
have in your process: Open, Passed, and Failed. The Actions to transition from one Status to another might
be specified as: Mark Open, Mark Passed, and Mark Failed. With these defined, you only need to decide to
which other Status(es) a Test Run can transition from any given Status.
A Test Run with the Open status cannot transition to that same status. Can it transition from Open to
Passed? It obviously can, so in the cell where Open intersects Passed, you select the Mark Passed action.
From Open status, a Test Run should also be able to transition to the Failed status, so you would select the
Mark Failed action where Open intersects Failed.
The end result for users is that they can only execute valid transitions, and they cannot bypass or skip any
process steps. For example, you might decide a Test Run should never directly transition from Failed to
Passed, but only from Failed to Open, you would set an action only in the Open column:
Users cannot then bypass the Open status and set Passed. There can be some important reasons for this
beyond mere policy. Transitions can be configured so that certain things happen when they are invoked:
field values are set or cleared, some programmatic function executes (such as prompting for electronic
signature), and so on.
Testing managers should analyze their needs and process to determine the statuses a Test Run can have
at the various stages of its lifecycle (e.g. "Open", "Planned", "Failed", etc.) Then the administrator can
create a Status definition for each one in the Statuses section of the Workflow Designer. Keep in mind
that you can have workflow configurations for different Test Run types, which means that different types
can have different sets of statuses, if that is what makes sense for the context. For example, Test Runs for
quick, experimental testing might have one set of status definitions, while Test Runs for formal regulatory
documentation might have a quite different set.
It is in the Actions section of the workflow configuration that you exert the greatest control over the
workflow. You can:
• Specify the role(s) that users must be assigned in order to be able to invoke the Action.
• Require that some field(s) be filled before the Action can be executed by specifying field ID(s) in the
Required Fields column.
• Specify fields whose values is cleared when the Action executes, by specifying the relevant field ID(s) in
the Cleared Fields column.
• Mark an Action as the initial one in the process. Remember that the Initial action, will execute along
with its required and cleared fields, workflow conditions, and workflow functions when a new Test Run
is created.
• Require an electronic signature from the user invoking the Action before the Action is executed.
• Specify one or more workflow Functions to execute when the Action executes - to set a date or run
some custom script, for example.
• Specify one or more workflow Conditions to control whether or not the workflow action can be
executed. If any of the conditions is not satisfied, users are informed that the corresponding action
as unavailable, and they are blocked from executing it. For example, a Condition might check that a
specific field is not empty, and the action is not available to users unless that Condition is satisfied.
For reference information about workflow Conditions and Functions, see Workflow conditions and
functions for Test Runs.
After Test Run workflow is set up and configured, when test results generated by external testing tools
are imported, the xUnitFileImport job processes the results according to the workflow configuration,
including conditions and functions for workflow actions, if workflow is configured for the project and the
Test Run type involved.
Polarion features US FDA-compliant electronic signatures, which can be applied to different artifacts,
including Test Runs. When configured, Polarion automatically maintains e-signatures as part of the overall
artifact history.
Tip
See Electronic signatures for details on how to configure LDAP or other external providers to
authenticate electronic signatures.
It is then easy to retrieve data to prove who signed what and when. Administrators can set configuration to
require electronic signatures from users when they:
Warning
For security, it is highly recommended to use the https protocol for access to Polarion when your
system is configured to use electronic signatures.
Caution
Your browser might offer to or autofill credentials in forms like e-signatures that use password fields.
Edit your browser settings or enforce the related security policies on managed computers to disable this.
The Test Run Workflow page of Administration has a section Actions, which defines the set of actions
users can invoke to transition a Test Run from one Status to any other allowed Status. The Actions table
has a column Requires Signature. When you check this option for any Action, users invoking that Action
are prompted to enter their username and password in lieu of their handwritten signature. (The dialog
requires two steps in order to require explicit action by the user, preventing browsers from supplying all
credentials.)
It can happen that after some workflow action has been executed, that another action is invoked that
renders existing signature(s) irrelevant. For example, a test manager might decide that a Test Run with
failed Test Cases should be executed again, and so sets the status back to the awaiting execution state. In
this case, any existing signatures previously applied to actions such as "mark passed" aren't really relevant
anymore.
To handle this situation, you can specify the workflow function MarkWorkflowSignaturesAsObsolete for
the relevant workflow action. In the example above, when the test manager invokes the action (which
could be configured as something like "Mark as Reopened"), all signatures from previous Test Run workflow
actions are marked as obsolete.
For each Test Run type defined, it is possible to require electronic signature when executing Test Cases
in Test Runs of the type. For example, if you have a type, Manual Security Test, you can configure it to
require a signature when executing Test Runs of that type:
This configuration is available globally (to provide a global default for new projects) and per project (in
which the global default can be overridden). You must have administrator permissions for the scope you
want to configure.
Tip
You can gather helpful testing information using SQL queries.
Procedure
2. Enter Administration, and then in Navigation select Testing Test Run Types.
3. In the Test Run Types page, check the Requires Signature for Test Case execution option for every
type for which you want to require Test Case execution signatures.
When this option is enabled, users executing Test Runs of the type configured are prompted to
electronically sign when they log the verdict for each Test Case executed during the Test Run. The Test
Records show an icon indicating that the user who executed the Test Case signed.
When Test Cases are exported to Excel for execution externally to Polarion, it is possible to require
electronic signature when a user imports Test Case results from Excel (using the "Import Manual Test
Results" action on the Test Run overview page.) Before importing Test Cases from Excel, configure the Test
Run type for your external tests to require electronic signature for execution of Test Cases, as described
in the previous section. Once configured, you can create Test Runs and export the Test Cases to Excel as
usual. When a user re-imports the Excel file to Polarion, that user is presented with a summary of the
executed Test Cases:
If the user proceeds with the import, s/he is prompted for electronic signature. The testing results are
imported, and the Test Run is updated only after the user completes the signature.
Polarion provides a default template for exporting Test Cases to Microsoft Excel. Administrators can
download the default template file which can then be used as the basis for one or more custom templates.
An administrator can upload customized template files which users can subsequently select as templates
for Excel files generated by exporting Test Cases to Excel. Custom templates can be uploaded in the global
scope, to serve as the default for new projects, or in specific projects.
Procedure
1. Log in with administrator permissions for the scope you want to access (global or project).
2. Open the repository if you want to access the global templates, or open the relevant project. (See:
Accessing Projects).
Procedure
1. On the Test Export Templates page, click on the template you want to download.
2. Click the Download button on the page header.
Procedure
1. Be sure you are working in the desired scope. For example, if you downloaded a global template and
want to use a modified version for a project, be sure to open the project. If you forget that, you will
overwrite the global template file with the modified file.
2. Open the Test Export Templates page (Navigation: Testing Test Export Templates).
3. On the page header, click the Upload button. In the Upload Export Template dialog, select the
template file on your local file system.
If you want to upload to overwrite an existing template, check this option in the Upload Export
Template dialog.
Tip
See Customize export templates for Microsoft Excel for details on how to create your own export
template for Excel.
For manual testing, it is possible for testers to track not only the overall results of a Test Case (passed/
failed), but also the results of each test step in a Test Case.
There is a special Work Item field Test Steps, to be used in Test Case type Work Items. It is rendered as a
table, with each row representing a discrete manual test step. Columns of the table are user-configurable.
You may need to enable test steps in your project configuration if the feature is not already enabled by the
project template. This section discusses these configurations.
When correctly configured, a table of test steps appears in the Custom Fields section of new Test Case
items in which testers can specify each test step (unless an administrator has configured the field to appear
separately on the Work Item detail form). This table is rendered as executable test steps in a panel below
the Test Run's table of Test Cases.
Tip
• Some project templates delivered with some products may have steps already configured. You can tell
by creating a new Test Case in the tracker and checking whether a Test Steps table is present. (You can
then cancel the Create Test Case operation without saving.) Even if Test Steps are pre-configured, you
may still want to customize the Test Steps table.
• You can optionally display Test Steps as a separate field in Test Case items, rather than in the Custom
Fields section.
To do this, you must edit the editor layout for the Test Case type ( Administration Work
Items Form Configuration).
If no Form Layout exists for the Test Case type, you can create one. (See: Configure Work Item Form
(Editor) layout).
In the layout configuration, add the Test Steps field (for example: <field id="testSteps"/>),
and remove the Test Steps field from the configured custom fields to be displayed:
In earlier implementations of the Test Steps feature, manual test steps were created and stored in the
Description field of Test Case type Work Items. In later implementations test steps are created and stored in
the dedicated Test Steps field described above. If you have projects in which test steps data are still stored
in Description fields, an administrator can migrate the existing data to the Test Steps field.
Polarion provides a special migration guide document, which explains how to perform this migration. The
guide is available online at https://www.polarion.com/hubfs/Docs/Guides_and_Manuals/Polarion-Test-
Steps-Migration-Guide.pdf.
You can enable the Test Steps feature either globally or per project. You can also add this configuration
to any existing custom project templates that for projects that include testing support. This process step
requires editing XML configuration code.
Procedure
Procedure
1. Log in with administrator permissions for the scope you want to configure (repository or project) and
enter Administration.
2. In Navigation, expand Work Items, select Form Configuration, and scroll the page to show the Form
Layouts section.
3. If there is no layout for the Test Case Work Item type, click Create New Form Layout and specify the
layout as described in Configure Interface Views.
If the table of layouts does contain a layout for the Test Case type (or whatever custom type of yours
corresponds to a test case), click the Edit button on its row in the table.
4. If the following element is not already present, add it below the execute-test extension element:
<extension counts="1,5,10" id="test-records" label="Test Records" />
5. Save the configuration. Note that you need to repeat this configuration in every Interface View that
has a form layout for Test Cases, and in which you want the Test Steps feature enabled for Test Cases.
You can create different Test Step table layouts for different Work Item types by using the Test Steps
custom field.
• You can set different Test Step table layouts for Work Item types where the Test Steps section in used.
• You can set individual Test Step layouts for Work Item types both on a Project and Global level.
• If there is no layout specified for a Work Item type, the default layout is used.
Tip
Looking to modify multiple Test Step tables in bulk? There's an extension for that.
You can edit the Test Steps layout configuration by doing the following:
To create a custom Test Steps table layout for the Work Item type, do the following:
Caution
If you change the ID of a column after updating the Test Steps table in a Work Item, all data in
that column gets deleted, even if the column's Name remains the same. (It's as if you deleted the
column and created a new one in a single action.)
6. Repeat the previous steps for all required columns. You can add additional columns by clicking and
adding a new row to the layout configuration.
7. Click Save when you defined all required Test Step columns.
Tip
• See the embedded Quick Help text on the configuration page for more information about how to
perform the configuration.
• If your users write up test case specifications in Documents, they must set the Document's
Work Item Presentation to show the Test Steps field in Document-based Work Items. For more
information, see Edit Test Steps in Documents.
• For more information on how to update the Test Steps table layout of a Work Item when an existing
configuration is changed, see Update the Test Step layout.
• For more information on limitations of the Test Steps feature, see Add, Edit, and Remove Test Steps
in Excel Round-trip.
By default, Polarion tracks the time spent on executing manual tests and includes it in Test Records that
are visible to all users with the necessary view permissions. There are some jurisdictions that prohibit the
visibility of the tracking an individuals' time.
Tip
This requires additional backend configuration. Contact your local partner or SaaS operations
representative for help.
If you need to stop tracking and displaying the time spent executing manual tests to comply with local
laws, there is a special system property you can use:
com.polarion.alm.ui.forms.extensions.disableTimeSpentRecording .
If set to "true", then the time spent during manual test execution is not stored within test records.
Note
Even if time recording is disabled and the time is not recorded, users will still see the clock running when
executing a test for a test record.
Procedure
You can control how many recent values are displayed in these drop-down lists, or hide the lists completely
(not recommended) using the maxRecentItems option in the Test Steps extension element of the Work
Item Editor layout configuration for Test Case type Work Items.
System Administrators can define the maximum number of test records to analyze by adding the following
property in the polarion.properties file:
com.polarion.alm.ui.forms.extensions.testExtensionRecordsLimit = 20
Polarion starts with the testExtensionRecordsLimit value, eliminates any duplicates or empty
results, then displays the maximum number of results defined in the maxRecentItems property.
Procedure
Note
Some project configurations may contain several different types of test cases: System Test Case,
Software Test Case, Mechanical Test Case, etc. You will need to perform the above configuration for
each of the test case types, assuming the editor layout contains the extension element enabling manual
Test Steps.
There is a job polarion.jobs.testruns.delete that deletes old Test Runs to free up system
resources and speed up system re-indexing. By default, this job will not run. An administrator can enable
it, and configure how the job selects Test Runs for deletion, in the global configuration and/or any project
configuration. In Administration Testing Configuration: Automated Cleanup of Test
Runs.
When enabling the job, the administrator may specify a query that returns the Test Runs to be deleted
by the job. (See the embedded Help in the Administration topic for more information and an example of
such a query.) When the job is enabled in the global scope, and no query is specified, the system will run
a default query that selects for deletion all Test Runs in all projects without a project-scope configuration.
Test Runs that are Test Run templates, and Test Runs having the Keep in History option set on them
will always be ignored by the job and will never be deleted. When Test Runs are deleted by the job, no
email notifications are generated, and nothing is shown in the Activity stream.
Automated Cleanup of Test Runs can be enabled and configured in projects to gain more precise control
of how the job deletes old Test Runs. Again, the administrator can specify a query, and it will apply only to
the current project. As in the global scope, the job will never delete any Test Runs that have the Keep in
History or the Is Template option set, even if the Test Run meets the search criteria in other respects.
(Note the Keep in History can be set in Test Run templates.) It is therefore not necessary to include
these as elements of the selection query. Be sure that users know to set Keep in History for Test Runs
that should have results preserved for traceability and proof of compliance, and check for existing Test
Runs that may need to have this option set before enabling the job and deleting old Test Runs.
Remember that all projects that do not have a project configuration for clean-up of old Test Runs will
have Test Runs deleted according to the global configuration settings in the Automated Cleanup of Test
Runs topic of Administration. This could be a problem if such projects contain Test Runs that need to be
preserved for proof of regulatory compliance, but to not have the Keep in History option set. Be sure
to do some checking before enabling the cleanup job in the global configuration.
If you want to schedule the cleanup job to start automatically, note that it cannot run on behalf of system
user because that user does not have write access to the Subversion repository. There is a parameter for
the job, userAccountValultKey that can point to a key in the User Account Vault so that the job will run on
behalf of this configured user, which should have the required SVN access. Generally, the same configured
user should also be used for xUnit import and automatic creation of Test Runs. If you have this configured,
just use the same user for the Test Run cleanup job.
Warning
Before running the job for the first time, be sure to check with project leaders to make sure that they
have set the Keep in History flag on all Test Runs that should be preserved in Project Baselines for
compliance reporting and other purposes.
Configure Plans
Polarion provides special pages called Plans to support planning and management of releases and
iterations leading to releases. Users can create Plans in projects, define milestones for them, set start
and end dates, add Work Items, and set properties that enable Polarion to monitor and report the status
and progress of Plans. For more conceptual information, see Plans Topic in the User Guide.
If your system has been updated from a Polarion version that did not yet have the Plans feature, you may
need to enable it in Administration. You can easily tell whether or not the Plans feature is enabled.
Procedure
Configuration options
There are several ways administrators can configure and customize Plans:
Related Topics
You can create custom data fields for use in Plans only. Plan custom fields should not be confused with
Work Item custom fields, which are defined for, and appear only in Work Items, or with Document
custom fields, which are defined for, and appear only in Documents. You can create Plan custom fields to
track any custom data you want to have associated with Plans. Plan custom fields can be of any supported
data type. You can select from a list of types when you create the fields. If you want users to be able
to select from a list of values for a Plan custom field, don't forget that you need to create a custom
enumeration before defining the Plan custom field. (For more information, see Configure Enumerations.)
Although Plans themselves can only be created in projects, you can define Plan custom fields in the Global
(repository) scope. Such fields defined globally appear by default in new Plans and Plan Templates created
in projects. Project configurations can optionally override the global configuration, changing the type,
semantics, or removing the field(s) from the project entirely. Plan custom fields can also be defined in
projects, where they will apply only to the specific project.
Procedure
1. Open the scope in which you want to define the Plan custom field(s) — Global Administration or a
specific project.
The configured Plan custom fields appear in the Custom Fields section of Plan and Plan Template pages,
and values for them can be added or modified in the Plan properties or Plan Template properties.
Note
You can create custom fields for Work Items and Documents that display an optionally filtered list of
Plans. For information, see Show a list of Plans in custom fields
Polarion provides a special field Plan Status for tracking the status of Plans. Users and reports can run
queries for Plans with a specified value or values in this field. The default Plan Templates provide three
status definitions: Open, In Progress, and Done. You can change the labels and other properties of these
statuses —. Building, Executing, Completed, for example. You can also add more statuses — Open, In
Review, In Progress, or Done, for example.
It is important to understand the Plan Status is not a workflow control like the Status field of Work
Items. There are no actions or transitions. It is simply a data item that provides a way of tracking and
communicating the current status of a Plan to stakeholders.
Although Plans themselves can only be created in projects, you can define Plan Statuses in the Global
Administration. The globally defined statuses appear by default in new Plans and Plan Templates
created in projects. Project configurations can optionally override the global configuration, changing the
semantics, or adding or removing statuses. Plan Statuses can also be defined in projects, where they will
apply only to the specific project.
Procedure
1. Open the scope in which you want to define the Plan custom field(s) — Global Administration, or a
specific project.
Tip
Left click on and keep the mouse button pressed to drag your items into the order that you want
them.
• Default: Select the Status that should be the initial one applied to new Plans. For example, the Open
status can be set as the default initial status for new Plans by selecting this property on the relevant row
in Plan Statuses. When a Plan's status changes to from the default status to any other, the Started On
property of the Plan is automatically set to the current date.
• Terminal: Select the status that should indicate that a Plan is finished. For example, the default Done
status can be set as the default end status for new Plans by selecting this property on the relevant row
in Plan Statuses. When a Plan's status changes to the terminal status, the Finished On property of the
Plan is automatically set to the current date.
Plan Templates are special versions of Plans that serve as a template from which actual Plans are created.
Values set in Plan Template properties become the default values for new Plans created by users and
based on the Plan Template. Plan Templates can be created only in the project scope. To access a project's
Plan Templates, open Administration Plans Plan Templates. You must have administrator
permissions for the project.
Procedure
1. Open the project for which you want to create a Plan Template.
Procedure
The Color property in Plan Templates is only present at the template level, and not in Plans created from
the template. The field accepts standard hex color notation used in web development. For example —
#nnnnnn, where #000000 is black, #ffffff is white, and so on. Standard web color names such as Red,
Blue, or Cyan, can also be used. The color specified in this field of the template is applied to the icon
that signifies Plan. Once a Plan is created from a Plan Template, the color field cannot be changed in the
properties of the created Plan.(Color is still editable in the Plan Template).
An important property to note is the option Report shared from Template. When selected, the Plan's
report page is shared in Plans instantiated from the Plan Template. Then, if a user invokes the action
to customize the Plan report, they are offered the option to customize either the report Page of
the instantiated Plan, or the report Page of the Plan Template. The user can perform the selected
customization, assuming that s/he has the necessary permissions.
The (Operations) menu in each Plan Template provides several functions you may need:
• Customize Plan Report: This action opens the underlying report Page of the Plan Template, enabling
you to customize the layout, modify parameters of existing Widgets, or add additional Widgets to
provide the desired functionality and information for the project team.
• Delete: Invoke this action to delete a Plan Template. Only the current Plan Template is deleted. Plans
that users have created from it are not affected and remain in the project.
Administrators can review, and optionally modify the default user permissions for Plans. Plan permissions
can be configured in both global (Repository) scope, and per project.For this configuration, you should be
familiar with the documentation on configuring user roles and user permissions.
Procedure
Available permissions
Administrators can review and modify the following permissions for Plans:
• Permission to READ - when granted, uses can view Plans but not modify or delete them.
• Permission to CREATE NEW - when granted, users can create new Plan objects in the system. Users
must also be granted permission to modify Plans.
• Permission to MODIFY - when granted, users can make changes to existing Plans. Granting this
permission is also required for the permission to create new Plans.
• Permission to DELETE - when granted, users can delete Plans from the system.
Note
Deleted Plans will still be shown in Baselines.
Polarion includes a special enumeration named Plan that can be used for Custom Fields, of the Enum
type. Such fields can be defined for Work Items, or for Documents. They display a list of Plans,
optionally enabling users to select one or more Plans in the list. The list of Plans can be filtered at design
time by specifying a query in the field configuration. If no query is specified, the list in the Custom Field
displays all Plans in the Project.
To implement a Custom Field that displays a list of Plans, follow this procedure:
Procedure
1. In the applicable project, create a new Collection, Document, Plan, Test Run, Test Record or Work
Item custom field.
2. In the Type column, choose Enum. A list field appears, listing available enumerations.
3. In the list of enumerations, select Plan. When selected, the Query field appears.
4. Optional. Enter a query, using Lucene syntax, to filter the list of Plans rendered in the list for end
users. For example, to have the Custom Field show only open Plans, enter status:open. (The
example assumes that the referenced status exists in the Plan status configuration.) To have the
field show all Plans in the Project, leave the Query field empty.
Tip
See the Enumeration types section for more information on the types of Enum Custom Fields you
can implement and a tip on how to create a query for the Query field.
Users with Global Administration access can define a custom template for My Polarion home pages.
Warning
If users modify their personal My Polarion page it will be decoupled from the global template.
Click at the top of the page then Reset to revert back to the default.
(Click Open Project or Project Group if Repository does not appear in your Recent list.)
2. Click Administration.
Tip
If you know the path to your target template page jump to Step 5.
If you don't, you can do the following:
Warning
All users should have access to the template and permission to read it.
Caution
Script block widgets will not work when the page displayed as a My Polarion page.
Note
Existing attachments will be viewed as static thumbnails when the page becomes a My Polarion page.
(You will not be able to access the Attachment sidebar or add new ones.)
Procedure
3. Click .
4. Click Download.
The page is downloaded to your browser's download folder as a .zip file.
Related Topics
Shortcuts quickly navigate users to some specific content and views of content in the Polarion portal.
Administrators can configure the global and project-specific default and favorite Shortcuts shown to end
users in Navigation. Shortcuts appear in the Global Shortcuts and Project Shortcuts topics of Navigation.
There is also a User Shortcuts topic, but administrators cannot configure default shortcuts for it. Shortcuts
configured as Favorites appear in the top section of the Navigation panel. See Navigation and Content
for more information.
Tip
You may need to use the expander control to access the Shortcut nodes in Navigation.
The default favorite Shortcuts you configure are shown to new users, and to users who reset Favorites, in
the Favorites section of Navigation . End users can customize their Favorites and may choose not to use
the configured defaults.
Global and project shortcuts can be modified by users who have permissions to do so via the Manage
Shortcuts topic in Navigation, accessible in the Tool view. They can add new shortcuts, and remove or
change the order of existing shortcuts. As an administrator, you can review Global and project shortcuts in
the Administration topics and remove any user-defined shortcuts that are outdated or inappropriate.
You can configure the default Shortcuts, shown in Favorites, that appear to new portal users, and existing
users who reset their Favorites. You can configure default favorite Shortcuts globally, for Project Groups,
and projects.
When working in project Administration, the project-scope configuration is located in Portal Default
Favorite Shortcuts. Settings in this scope override those of the global configuration, which is propagated
to Default Favorite Shortcuts in projects.
This configuration requires editing of XML code. It is normally performed directly in the Administration
page using the editor provided. Look at the demo projects that ship with Polarion for examples.
You can configure the content of the Shortcuts topics that appear in Navigation. Shortcuts can provide
users with quick access to actions like creating a new Work Item), to subsets of Work Items also including
the Work Item view), to Documents and Pages, Plans, or any other content.
Note
Shortcuts are simply time-saving navigational aids. They do not evaluate user permissions.
Consequently, some users invoking a Shortcut may find they do not have permission to access the
target content.
Configuration data is stored in the shortcuts.xml file for the relevant scope. You can edit this file
directly in Administration, or download it, edit offline, and upload back to the server. When you configure
global-scope Shortcuts for a repository, they appear as nodes under the Global Shortcuts topic in
Navigation. When you configure Shortcuts for a project, they appear under Project Shortcuts when users
open the respective project.
Procedure
1. Log on with administrator permissions for the scope you want to configure. If your system is
configured with multiple repositories, be sure you log on to the repository you want to work with.
2. Enter Administration.
3. If you want to configure global Shortcuts, open the Repository.
If you want to configure shortcuts for a project, open the desired project.
You can either edit the configuration online in the text editor found on the configuration page, or you can
download the XML configuration file, edit it with a preferred tool, and use the Import from file to add it
back to the portal.
The best way to familiarize yourself with the XML is to look at the default global configuration, and
the project configuration for the example projects included with Polarion. For example, you can readily
see that a shortcut to a set of Work Items involves embedding the syntax of some query in the query
parameter of a <shortcut> element.
For example, this shortcut would show unresolved Work Items with the Suspect flag set:
Tip
You can build a query visually in the Work Items page (not the Administration page), and use the
Convert to Text option in the Visual Query Builder to convert the query specified in the visual elements
to text. You can then copy and use the textual query in the query parameter,
You can configure Polarion to support multiple human language translations of Work Items. When
correctly configured, Title and Description fields for one or more languages, (in addition to the default
language of the portal), appear in the Document Editor. When Work Items configured with support for
multiple languages are contained in Documents, users viewing them in that context can switch languages
to view Work Items in the selected language.
Multilanguage support can be configured globally for the repository, and per Project. You can optionally
configure different languages for different Work Item types, and multiple languages for a single type.
Procedure
1. Define custom fields to store translated text for Work Item Titles and Descriptions.
2. Add language configurations for supported translation languages.
What to do next
Note
Headings require additional configuration if you want to customize them.
The first step in multilanguage configuration is to define custom Work Item fields to store translated text
of Work Item titles and descriptions.
You need to define two custom fields for each language you want to support — one for the translation of
the Work Item title, and one for the translation of the Work Item description. The field for the title should
be of type string. The field for description should be of type Rich Text (multiline). You need to
define this field pair for each Work Item type that needs to support multiple languages. In each Work Item
custom field configuration you need this field pair for each language that must be supported.
For example, suppose that for Work Items of a type named Requirement you need to support translations
for German and Japanese. In the Custom Fields configuration for the Requirement type, you would need
to specify:
• Two fields for German, with IDs like requirement_title_de (a string field for the German title), and
requirement_descr_de (a multiline rich text field for the German description). The Name property
can be something like Title (DE) and Description (DE). Alternatively, the value could be written
in the target language — Titel and Beschreibung, for example.
• Two fields for Japanese, with IDs like requirement_title_jp and requirement_descr_jp, and
names like Title (JP) and Description (JP) (or these words translated to and rendered in
Japanese).
When all the necessary custom fields are defined, the next step is to configure languages.
Headings
For Heading Work Items, you only need to define a single custom field for the translation of the Title
because Heading Descriptions never appear in the Document.
You'll also have to add this field to the Heading Work Item Form (Editor) layout.
To define a custom field for Headings, you must define them as a Work Item type.
You perform this configuration in the Administration Portal Languages in the scope you
want to configure. You can perform the following configurations on this page.
The first item in the table on the Languages page is the configured label for the control in the Document
Editor that enables users to switch from a configured translation to the default language of the portal. In
English versions of the Polarion portal, the value is the English string Default Language.
To change the default, click the Create button on the table row. Then on the Default Language page,
change the value of the label and click the Save button.
Add a language
Tip
Before adding a language to the configuration, be sure you have created the necessary custom fields to
store the translated title and description for each target language.
Procedure
You should repeat this configuration for each language for which you want to support translations.
On the Languages page, you can edit any existing language configuration, or delete a language
configuration. Deleting a language configuration simply removes the language item from the Switch
Language menu. It does not remove any translation data that users have added to Work Items. If you want
to remove such data, you must remove the custom fields from the Work Items configuration, and then
reindex the system.
Non-Latin alphabets
This topic provides reference information for users and System Administrators about features and
configurations related to using Polarion with non-Latin alphabets.
The Polarion architecture is designed to enable localization of the system to any language. For information
on the availability of localized versions of Polarion, contact the Polarion sales organization.
This section documents system properties that generally need to be set by administrators in the system
configuration in order for some feature(s) to work with non-Latin characters or languages.
com.polarion.customWordSpacingCharacters
Language: Japanese. Enables Document comparison with languages that do not separate words with
spaces. Specify a "break" character to be used when users compare Document versions in the Document
history. Multiple characters can be specified and breaks occur on every one of them. For example:
com.polarion.customWordSpacingCharacters=\u3000\u3001\u3002\uff08\uff09\uff0c\
uff0e\uff61\uff64
com.polarion.placeCommentsDirectly
Language: Japanese. When set to true, then comments are placed directly under the cursor. If false, then
comments are placed after current word.
Note
documents.create.japanese.kanji.transliteration
Chinese is set by default, but this property lets you switch the transliteration to Japanese romanization.
Transliterated values in Polarion are used for auto-filling fields that require ASCII symbols in the
Document, Page, and Plan creation dialog boxes.
Tip
You can disable the auto-filling of these fields by setting the
com.siemens.polarion.ui.nameIdAutoFilling.enabled system property to false.
Users who switch between English and Japanese keyboard should note that when using the Japanese
keyboard, entering Japanese characters in a graphical query element's panel (in the Work Items Table
view) does not invoke the search action. The user must press Enter or Return to initiate searching. This is
different behavior from English keyboard and characters, where search is invoked automatically with each
character entered.
Diagram fonts
Only diagrams that use Helvetica font can be properly rendered by the Document Editor into an image
that is displayed in the content of a Document or Work Item. Making other fonts work with Asian or
other non-Latin languages is fairly complex and requires considerable effort and will most likely require
assistance from Polarion Professional Services. If you need this capability for diagrams, please contact
Polarion customer service on Support Center for guidance.
You can configure different variants of the Polarion user interface for end users who work with the Polarion
platform in different contexts or user roles. For example, one user may function as a manager at some
times, and as a developer at other times. You can configure different Interface Views (Views) which
provide varying levels of information and presentation, displaying just the navigation topics, Work Item
field content and Work Item Editor layout needed for a given work context or role.
A default Interface View is defined in the default global configuration, and in Project Templates. Project
administrators can override the global or template configuration and define a custom set of Interface Views
for any project.
Tip
Polarion comes with a Compact view for users with small displays, and a High Contrast view for people
with who have color visual impairment .
Generally, Interface Views should have descriptive names that describe the role of people for whom they
are intended. For example:
Bear in mind that Polarion's default Project Templates can be customized, and/or custom variants can be
created. What Interface Views exist, what information any View provides, and how it is laid out, depends
on how the template developer configured Interface Views in the project template.
Warning
Interface Views are not a security feature. They do not prevent any users from having access to any
information. User roles and permissions should be used to control users' access to portal content.
Configuration scope
You can customize interface Views to change the display of navigation topics, Work Item fields, and
the Work Item Editor.
You can define Views globally for each Repository, and for each project.
• The global configuration is inherited by each project, unless overridden by a project template, and the
settings for each of the globally defined Views can be modified in projects in addition to those provided
by the project template.
• You can also create new Interface Views that specify the Navigation topics, Work Item fields and the
Work Item Editor to display when a user selects the View in Navigation.
Select a View
You must have administrator permissions for the scope you want to configure.
Process overview
• Portal Views - This is where you specify what Interface Views exist in the configuration for the
scope you are configuring.
• Portal Topics - This is where you specify which Navigation topics appear in each Interface View.
• Work Items Form Configuration - This is where you specify what information is shown on the
Work Item Editor (Form Filters), and the editor layout to be used when a user is working in the Interface
Views.
Procedure
1. Create a new interface View in the desired scope, or access an existing interface View.
2. Configure field filtering for the Work Item Editor to control what fields appear in the editor when a
user invokes the Interface View.
3. Configure the layout of Work Item Editor fields to control how the fields shown via the filtering
configuration are laid out when a user invokes the Interface View.
4. Configure the list of Navigation topics to display when a user invokes the Interface View.
Subtopics of this topic provide more detail about each of these main steps.
Inheritance scheme
It is important to understand that when a new Work Item Form (Editor) filter or Work Item Form (Editor)
layout configuration is created, its content is prefilled with its parent configuration. The inheritance
scheme is as follows:
When at least one ALM license is present on the server, the following View-related features are available:
• Multiple Views are configurable, and accessible to users in the web interface.
• Form Configuration (layouts and filters) per View.
• Form Menus (linked and linking) per View.
• Read-only Fields per View.
• Topics configuration per View.
• Form Configuration (layouts + filters), Read-only Fields, and Navigation topics are configurable only for
the _default View.
• Interface Views are not visible or accessible to users.
• Form Menus (linked and linking) are not exposed in the user interface and the configuration is not
applied.
Procedure
1. Open the project or repository in which you want to create a new Interface View, and enter
Administration.
2. In the Navigation pane, expand Portal and select Views. The Views page appears and displays a
table listing the Interface Views currently existing the scope in which you are working.
3. In the table, click the Create New View button. An edit form appears in the bottom part of the page.
4. Enter a unique ID for the new View. Use letters, numbers, underscore, but no spaces — techWriter
for example.
The system derives a value for Name from your input. This value will appear in the View list in
the Tools view of Navigation when a user opens the project or repository. For example, if you enter
techWriter, then Name will appear as Tech Writer.
5. If you want the Interface View to be available only to users who have a specific role assigned them in
the User Management configuration, specify the role(s) in the Limited to Roles section.
6. Click the Create button to create the new Interface View. (To show the new View in the table, click
Refresh.
A new Interface View does not differ from the default in terms of Navigation topics, Work Item fields
shown, and Work Item Editor layout. It is necessary to address these configurations for the new View. They
are covered is other Help topics. See Configure Work Item Form (Editor) Filters, Configure Work Item
Form (Editor) Layout, Define Read-only Fields, and Control Navigation Topics.
You may need to access an existing Interface View configuration to modify roles, or delete the definition.
Procedure
1. Open the project or repository where the Interface View you want to access is configured and enter
Administration.
2. In the Navigation pane, expand Portal and select Views. The administration page displays a table
listing the Interface Views currently existing the scope in which you are working.
3. In the table, select one of the existing Views. Detail information appears in the bottom section of the
page.
If you want to delete an Interface View definition, select it according to the steps above. With the desired
Interface View selected, click the Delete button in the toolbar of the part of the page.
Related Topics
You can configure filtering of the Work Item Editor for any Interface View. Filtering can hide some fields,
or set some fields as read-only for different workflow actions and statuses. Filtering is activated by clicking
the Filter button on the Work Items form toolbar. Remember that this is not a mechanism for securely
restricting access to fields. Users can restore visibility and editing of fields hidden by filtering at any time.
Procedure
1. Open the project or repository that has the Interface View for which you want to configure form
filtering, and enter Administration.
2. In the Navigation pane, select Work Items Form Configuration. The Form Configuration page
appears.
The Form Configuration page contains two main sections. The first section is Form Filters. You can either
create a new form filter, edit an existing form filter, or remove an existing form filter.
Procedure
1. In the Form Filters section of the Form Configuration page, click the Create New Form Filter
button. The Create New Form Filter dialog box appears.
2. In the View list, select the Interface View you want to configure. If you want the form filtered only for
a specific type of Work Item, select the type from the Work Item Type list. After selecting the desired
list value(s), click the Next button. The Form Filter Configuration page loads in your browser.
If you are working in a project, values in the Actions and Statuses sections are inherited from the
global configuration. You can make changes as desired for the project.
3. If necessary, scroll the page to expose the embedded Quick Help info for the page. Use this
information to specify the Actions and Statuses comprising the filter.
4. When you have finished with the filter parameters, click the Save button in the bar below the page
heading.
5. To return to the Form Configuration page, use the text link Return to Form Configuration at the top
of the page.
Procedure
1. Navigate to the Work Items Form Configuration topic as described in Access the
configuration, above. Be sure you are working in the correct project or repository.
2. In the Form Filters section, find the filter you want to modify in the table.
3. Click the Edit button. The Form Filters page appears.
4. Change the settings on the Form Filter Configuration page, referring to the embedded Quick Help
information (scroll down if it is out of view).
5. Click Save when finished, or the Cancel button to undo unsaved changes.
Procedure
1. Navigate to the Work Items Form Configuration topic as described in Access the
configuration, above. Be sure you are in the correct project or repository.
2. In the Form Filters section, find the filter you want to remove in the table.
3. Click the Delete button and respond affirmatively to the confirmation prompt.
Tip
Global configuration for the -- Default -- Interface View plus the -- unspecific -- Work Item
type cannot be deleted because it is the basis from which other configurations are derived.
Related Topics
Administrators can customize what extensions appear in a Work Item and how they are loaded.
Note
If a Requirements or QA license is present on a server where no ALM license is present, then multiple
Interface Views are not available, and only the editor layout of the Default View is configurable.
For any Interface View, you can configure the layout of the fields on the Work Item Editor. This
editor enables viewing and editing of Work Item details in the lower half of the Table presentation of
Work Items (both Document-based and Tracker-based) when you select a Work Item in the table. This
configuration requires editing an XML configuration file. Administration provides access to this file and a
basic online XML editor enabling you to edit the file online without leaving your browser. Alternatively, you
can copy the XML from the online editor, paste it into your favorite XML editor to work on it, and finally
past the modified XML back to the online editor.
Tip
• You can limit the number of Work Item links that appear in Work Item titles, and other places for
increased performance and usability.
• Configurations made here, including the read-only field flag, have no impact on the Work Item tables.
If you want to define a read-only field that is also read-only in Work Item tables, See Define Read-
only fields.
This topic explains how to access the configuration data and the online editor. Comments embedded in
the XML code, plus embedded Quick Help on the editor page provides information about the elements and
attributes used in the configuration.
Procedure
1. Open the project or repository that you want to configure the Work Item Editor layout for, and enter
Administration.
2. In the Navigation pane, select Work Items Form Configuration. The Form Configuration
page loads.
3. Find the Form Layouts section of the page (scroll down if necessary). That section enables you to
create a new editor layouts, and presents a table of existing Interface Views having a customized
Work Item Editor layout. You can edit or remove any existing editor layout.
The Interface View for which you want to create a custom editor layout must already exist. That is, you
cannot create new View during the editor layout configuration process.
Procedure
1. Navigate to the Form Configuration page as described in the previous set of steps.
2. In the Form Configurations section, click the Create New Form Layout button. The Create New
Form Layout dialog box appears.
3. In the View list, select the Interface View you want to configure. If you want the layout of the Work
Item Editor to apply only for a specific type of Work Items, select the type from the Work Item Type
list. After selecting the desired list value(s), click the Next button. The Form Layout Configuration
page loads in your browser.
4. In the embedded XML editor, edit as needed to create the layout you want for the selected View and
Work Item type (if you selected one). Refer to the embedded Quick Help text on the page (scroll
down if necessary to see it).
Caution
Adding a custom field with an ID that matches an existing field (like ID, Description, Title, etc.) is
not supported and might lead to unexpected behavior.
5. Save your configuration when you finish editing. As soon as you change anything in the XML editor,
the Save and Cancel buttons become enabled. These enable you to save changes or abandon any
unsaved changes.
Procedure
1. Open the project or repository which contains the Interface View you want to modify.
Procedure
1. Navigate to the Work Items Form Configuration topic as described in Access the Form
Layout configuration, above. Be sure you are working in the correct project or repository.
2. In the table in the Form Layouts section of the page, find the layout you want to remove.
3. Click the Delete button on the layout's row in the table, and respond affirmatively to the confirmation
prompt.
Note
Global configuration for the -- Default -- Interface View plus the -- unspecific -- type cannot
be deleted because it is the basis from which other configurations are derived.
Asynchronous loading (enabled by default) ensures that if your Polarion is integrated with external
repositories like Gitlab and Bitbucket or applications like Jira or Microsoft TFS and there's a connection
issue on the third-party's side, then the rest of the Work Item will still load.
(The ability to disable asynchronous loading is expected to be removed in future Polarion releases.)
Procedure
You can limit the number of linked items displayed in Work Item titles to decrease load time and improve
usability.
(Prevents Work Items from getting cluttered with potentially hundreds of links in their titles.)
If you click on More... you scroll right to the Linked Work Items section. (Where all of the links are
listed.)
Note
There may be a slight delay after clicking the link if there are a large number of linked Work Items.
• The Linked Work Items section of the Work Item Editor before you enter Edit mode.
◦ Click the number of links to view all of the linked Work Items.
◦ When you click Edit in the Work Item Editor, all of the links appear in the Linked Work Items
section.
• The Links section of the Work Item Properties Sidebar in Documents.
(More... in the table is just informational. You can view the full list in the Work Item's Linked Work
Items section. )
• External links (like OSLC links) are ignored by the limit and are separated by the | symbol.
This feature is enabled out-of-the-box (with a default of 100 Work Items) even if the property is not visible
under Configuration Properties.
You can disable it or change the number of visible Work Items by doing the following:
1. Open Repository or a Project, depending on which scope you want the settings to affect.
Tip
If you want a runtime property setting to apply to multiple projects, but not globally to all projects,
you need to set the property in each of the desired projects.
• No links appear when set to 0. (But if you click on the number of links you scroll to the complete
list in the Linked Work Items section.)
• The limit applies to links and backlinks independently. (100 links and 100 backlinks appear.)
• When set to a negative number (-1) the feature is disabled, and all links are listed in Work Item
headers.
3. Change the value of the workitems.linkedWorkItemsLimit= property (or add it if it's not
there), and click Save.
Limitations
• The limited link list is sorted differently than the full list in the Linked Work Items section.
• If you do not have the Linked Work Items section (<field id="linkedWorkItems"/>) in your
project's Work Item layout configuration, then clicking on the number of links in the title will have no
effect.
(It cannot jump to a section of the Work Item that does not exist.)
• In rare cases, the number of hidden Work Item links may not be exact.
You can render custom panels on the Work Item Editor with Velocity, HTML or JavaScript.
Tip
• With Velocity scripts, you can access Open API objects like $trackerService.
◦ It also allows access to the Rendering API. ($transaction)
◦ It references the current Work Item being used via $object.
• To check the access rights and persistence of a Work Item use:
#if(!$object.isUnresolvable() && $object.isPersisted())
• To get the Rendering API version of a Work Item use:
#set($wi = $transaction.workItems().getBy().oldApiObject($object))
• To use the .render() method of the Rendering API, make sure to specify the format and target
for .render():
$wi.render().htmlFor().forFrame()
Procedure
Note
Scripts are implemented in the following order:
3. In the Navigation pane, select Work Items Form Configuration. The Form Configuration
page loads.
Tip
If you add scripts in a sub folder just add it to the script path.
<extension id="velocity_form" label="Velocity Form"
script="[sub_folder_name]/my_script.vm"/>
6. Click Save.
Known Limitations
• In Polarion versions older than 2019 SR2, JavaScript execution is not supported.
(Polarion 2019 SR3 brought full support for JavaScript execution in all Work Item Editor Extensions.)
Related Topics
Unless configured as read-only, many fields can be edited in place without invoking edit mode for the
entire Work Item. In each Interface View configuration, you can define what fields should be read-only
when a Work Item is viewed or edited. The configuration can include custom fields. You can perform
this configuration for any Interface View in which you want specific fields to be read-only, either always,
or when the Work Item enters a specific workflow status. For example, when a Requirement has the
<Accepted> status, you can make the Description field read-only for anyone using a specific Interface
View.
The same Read-only restrictions provided by the configuration apply to bulk-edited Work Items. In the
Matrix presentation, only restrictions for linked Work Items are applied, meaning that links cannot be
added. In the Time Sheet presentation, only restrictions for work records, time spent and remaining
estimate are applied, meaning that work records cannot be added or edited. The Read-only configuration
applies the same restrictions for Inline editing in the Work Item table.
Tip
If you're looking to restrict the modification of object attributes depending on their workflow state, don't
use read-only fields. Use permission custom sets instead. Read-only fields are not a security feature,
but rather a convenience legacy feature that only works only in the Polarion UI and not on the API
level, or for imports and exports. To set up a robust process control that spans all layers of Polarion
functionality, you must configure per-field permissions in combination with permission custom sets.
Read-only field configuration is available for both the global (repository) and project scopes. Remember
the project settings override the global settings, which are the default for new projects.
Procedure
1. Log on to the portal with administrator permissions for the scope you want to configure.
2. Open the repository or the project you want to configure, and then enter Administration.
3. In Navigation, expand Work Items and select Read Only Fields. The Read-only Fields page loads
in your browser.
Note
If the table already contains some configured statuses and fields, it is possible to remove these by
clicking the in the relevant row if these configuration are no longer desired.
7. When you have completed the configuration, save your changes using the Save button located on the
page.
Tip
You can use a special command @all to specify that all fields (including custom fields) should be
read-only. You can specify exceptions — writable fields, for example — by specifying the desired fields
prefixed with a dash character (-). More information, command syntax, and an example are provided in
the embedded Quick Help on the configuration page in Administration.
Related Topics
For each Interface View configured, you can control which topics appear in Navigation when a user selects
the View. For example, you might create a tech writer view, and decide that users invoking it only need to
see the Work Items and Documents and Pages topics in addition to the Home and project and
user Shortcuts topics.
1. Open the repository or project you want to configure and enter Administration.
2. In Navigation, expand Portal and select Topics. The Topics page loads.
3. If you want to create a new configuration, click the Create New Topics Configuration button. In the
dialog box, select the Interface View you want to configure.
If you want to modify an existing configuration, click the Edit button on the row of the configuration
you want to modify.
In both the above cases, an online XML editor appears with the XML code of the selected
configuration.
4. In the online XML editor, comment out or remove elements in the <topics> element which
correspond to the Navigation topics you want to hide, leaving only the elements for the topics to
show. For example, your configuration for the previously mentioned Tech Writer View might be
something like the following:
Configure Reports
There are two basic types of reports: Source code reports which appear in the Reports topic of the
portal, and Audits/Metrics reports which appear in various dashboards. All reports are customizable in
Administration by means of XML configuration files. This topic explains the basics of how to configure the
different types of reports.
You can configure source code reports for each project. If you are not familiar with the basics of the
different scopes, you may want to review The Administration Interface.
• Maven Site
• Unit Test Coverage
• Unit Tests
• Javadoc
• XRef
Two additional reports are available, but are commented out in the default reports configuration file:
• PMD
• Checkstyle
reports-config.xml Defines the list of source code reports shown in the Reports topic of the portal.
descriptors.xml Configures the calculations used by the reports defined in reports-config.xml.
Procedure
1. Log on with administrator permissions for the project you want to configure.
2. Enter Administration.
3. If you are not already working in the project you want to configure, open the Open Project or Project
Group dialog box, and select the project to open it.
Tip
If there's no Project configuration, you can click Import from global level to load the XML from
the global configuration into the online XML editor.
(You can then customize it to suit your project. When you Save, a Project configuration link will
appear at the top.)
6. You can edit the configuration files directly or download the Project and Global links to edit them
offline.
7. If you edit a file offline, click Import from file to add it back to the Polarion repository.
The configuration files contain comments that explain the various elements and attributes.
Note
Source code reports can be computed only if the build artifact containing Java sources is a maven2
build artifact, and the build process is running without errors. The Configure building topic for more
information on building features and build management.
Work Item metrics are Work Item-related values (facts) that are calculated by Polarion on projects and
project groups. There are two related calculations: trackeranalysis, which calculates metrics on projects,
and trackeranalysis-projectgroup, which calculates metrics on project groups.
Caution
Work Item metrics are deprecated and scheduled for removal.
You can configure Work Item metrics for projects. If you are not familiar with the basics of the different
scopes, you should review:Administration Interface.
This configuration contains elements that define values that may be shown on a dashboard, or used in the
definition of a trend chart.
Work Item metrics are configured in the workitem-metrics.xml file. To access this file:
Caution
Work Item metrics are deprecated and scheduled for removal.
Procedure
1. Log on with administrator permissions for the project you want to configure.
2. Enter Administration.
3. If you are not already working in the project you want to configure, open the Open Project or Project
Group dialog box, and select the project to open it.
What to do next
The configuration file contains comments that explain the elements, their use, and options for
customization.
The workitem-metrics.xml file defines which Work Item metrics will be calculated on projects during the
trackeranalysis calculation. The basic XML syntax and elements are shown in the following code example:
Caution
Work Item metrics are deprecated and scheduled for removal.
<workitem-metrics>
<metrics>
<entry>
<key>KEY</key>
<label>LABEL</label>
<description>DESCRIPTION</description>
<value type="TYPE" ...>
...
</value>
</entry>
...
</metrics>
</workitem-metrics>
Where:
KEY is a unique identifier for the metric, to be used when referencing the value, in a
dashboard, for example. Required.
LABEL is a text label for the metric. Optional only for in-place defined metrics.
DESCRIPTION is a longer text description for the metric. Optional only for in-place defined metrics.
TYPE is the type of the metric — integer, distribution, or percentage. Required only for in-
place defined metrics.
By default the configuration contains a number of internally defined metrics. For example:
Caution
Work Item metrics are deprecated and scheduled for removal.
<entry>
<key>UNRESOLVED-BY-TIMEPOINT</key>
</entry>
<entry>
<key>MAI</key>
</entry>
You can optionally remove any of these elements. If removed, the internally defined metric will not be
calculated during the trackeranalysis calculation. For the complete list of the internally defined Work Item
metrics, see the Administration Reference topic Internally Defined Work Item Metrics.
The way the value is calculated is described by the value of subelement. There are four types of in-place
defined metrics:
Caution
Work Item metrics are deprecated and scheduled for removal.
int Integer value defined as the size of the search result of a Work Item query. Example:
<entry>
<key>OPEN</key>
<label>Open</label>
<value type="int">
<query>resolution:###### NULL</query>
</value>
</entry>
In this example the value of the metric OPEN will be the number of Work Items having no
resolution value set.
distribution There are 2 ways a distribution value can be defined: using an enumeration, and using
queries.
Syntax:
Where...
• reverseOrder - if set to true, the values in the distribution will be sorted in reverse
order with respect to the sort order of the enumeration options. (Optional)
• unresolvedOnly (deprecated) - if set to true, only unresolved items will be counted.
(Optional)
• resolvedOnly (deprecated) - if set to true, only resolved items will be counted.
(Optional)
The order of values in the distribution is defined by the sort order of the options in the
enumeration. ID and label of subvalues is ID and label of the corresponding enumeration
option.
Example:
<entry>
<key>DEFECTS-BY-RISK</key>
<label>Defects by Risk</label>
<value type="distribution" enumeration="defect:enum:risk"
query="type:defect AND
risk:$option$" reverseOrder="true"/>
</entry>
<entry>
<key>REQ-BY-RELEASE</key>
<label>Requirements By Release</label>
<value type="distribution" enumeration="enum:release"
query="type:requirement AND
targetRelease:$option$"/>
</entry>
Syntax:
<value type="distribution">
<query id="..." label="...">...</query>
...
</value>
Where:
This method uses subelements query of the value element. Each such subelement
corresponds to one value in the distribution, and the value is defined as size of its search
result.
Example:
<entry>
<key>RESOLVED-RATIO</key>
<label>Resolved vs. Unresolved</label>
<description>Rate of Work Items that have resolution set.</
description>
<value type="distribution">
<query id="resolved" label="Resolved">NOT
resolution:###### NULL</query>
<query id="not-resolved"
label="Unresolved">resolution:###### NULL</query>
</value>
</entry>
items- Syntax:
traceability
<value type="items-traceability">
<itemsQuery>...</itemsQuery>
<links>
<link id="..." backLink="..."/>
...
</links>
<coverageQuery>...</coverageQuery>
</value>
Where:
• itemsQuery is a query that defines the set of Work Items, starting from the path of
which, and consisting of Work Item links, will be searched for.
• links defines which links can be part of the path.
• link/id is the ID of the link role (or a regular expression matching link role IDs) that
can be part of the path.
• link/backLink if set to true, only incoming link of the matching ID can be in the
path (otherwise only outgoing).
• coverageQuery is a query that defines a set of items whose path is searched for. (You
can use the special value has-linked-revisions that matches items having at least
one linked revision.)
Each metric of this type defines a notion of traceability of Work Items. The value is a
distribution with two integer subvalues: count of traceable and not-traceable items among
those that satisfy itemsQuery. Traceable items are those, from which one can find a path
consisting of links matching some conditions (defined by link elements) that leads to at
least one item that satisfies the coverageQuery. Items that satisfy both itemsQuery
and coverageQuery are automatically considered traceable without checking links.
(Empty path is always acceptable).
Example:
<entry>
<key>TRACEABILITY-REQUIREMENTS-COMMITS</key>
<label>Traceability Work Items to Commits</label>
<description>
Rate of Work Items that are linked to commits.
</description>
<value type="items-traceability">
<itemsQuery>HAS_VALUE:resolution</itemsQuery>
<links>
<link id=".*" backLink="true"/>
<link id=".*" backLink="false"/>
</links>
<coverageQuery>has-linked-revisions</coverageQuery>
</value>
</entry>
commits- This is very similar to items-traceability. The only difference is that there is no
traceability element itemsQuery; - the path is searched from all Work Items that are linked to at
least one revision (commit) in the project. The subvalues in the distribution correspond to
the count of project revisions that are linked to traceable Work Items, and to the count of
project revisions that are not linked to a traceable Work Item.
Example:
<entry>
<key>TRACEABILITY-COMMITS-REQUIREMENTS</key>
<label>Traceability commits to Work Items</label>
<description>
Rate of Commits that are linked to Work Items.
</description>
<value type="commits-traceability">
<links>
<link id=".*" backLink="false"/>
<link id=".*" backLink="true"/>
</links>
<coverageQuery></coverageQuery>
</value>
</entry>
Calculates the sum or average of values stored in a custom field. Configured as the field attribute of
Work Items returned by a query that is specified as the query' attribute. Calculations are only possible for
number type fields. such as integer, float, or currency.
Example:
You can configure the Work Item Quality report for each project. If you are not familiar with the basics of
the different scopes, you may want to review Administration Basics: The Administration Interface.
Caution
The Work Item Quality report is deprecated and scheduled for removal.
This configuration enables you to define which of the available metrics should appear in the dashboard.
Procedure
1. Log on with administrator permissions for the project you want to configure.
2. Enter Administration.
3. If you are not already working in the project you want to configure, open the Open Project or Project
Group dialog box, and select the project to open it.
Note
If you edit a file offline, click Import from file to add it back to the Polarion repository.
You can configure the Process Quality report for each project. If you are not familiar with the basics of the
different scopes, you may want to reviewAdministration Interface .
Caution
The Process Quality Report is deprecated and scheduled for removal.
Process audit rules for the process quality report are configured in the rule-settings.xml file. The file
is commented to help you understand the elements and options. To access this file:
Procedure
1. Log on with administrator permissions for the project you want to configure.
2. Enter Administration.
3. If you are not already working in the project you want to configure, open the Open Project or Project
Group dialog box, and select the project to open it.
6. Use the appropriate link in the Configuration section of the respective configuration page to
download the configuration file to your local system, or edit it online using the text editor provided on
the configuration page.
7. If you edit a file offline, click Import from file to add it back to the Polarion repository.
The Documents & Pages topic of Administration presents the following configuration options:
Sometimes it can be useful classify Polarion LiveDoc documents (Documents) by type. For example, you
might want to have different Document types for different types of specifications. Also, there can be a need
to have workflow control over entire Documents in order to establish traceability for some process related
to Documents. For example, you might want to have Document statuses such as Draft, Under Review,
Reviewed, and Approved, and be able to transition entire Documents through these statuses.
When Document types are configured, users can assign a type to new or existing Documents in the
Document Properties sidebar of the Document Editor, and view the assigned type there.
Note
Most of the default project templates have preconfigured Document types and Document workflows.
(There are more project templates available on the Polarion Extensions Portal that may also have these
configured). Explore whether a template can meet your needs before deciding to customize.
The default Project Templates and demo projects are preconfigured not only with Document types and
workflow, but also underlying permissions that go together to help control the workflow. For example,
the content of Documents of the Requirements Specification type (predefined in several templates)
cannot be modified if the workflow status is inReview or Approved.
You can configure Document types and Document workflow globally and per project. Remember that
the Global configuration provides the default that is used for all projects not having a project-scope
configuration. Document types and Document workflow must be explicitly enabled by an administrator
before the features are available to end users.
Warning
Poorly written code on a Wiki or LiveDoc ™ (Rich Text) page can leave your system open to XSS
(Cross-site scripting) attacks using malicious Work Item and API calls. (Anything, Java code included, can
be added to a Work Item in the document and the API will return the actual value of the target fields.)
• Restrict the number of users that can modify Wiki and LiveDoc ™ (Rich Text) pages.
• Administrators should notify any users that modify Wiki and LiveDoc (Rich Text) pages of the
information below:
• Use the Rendering API (If $workItem is an instance of
com.polarion.alm.shared.api.model.wi.WorkItem):
$workItem.title.render
• If it is not possible to use the Rendering API the use the following;
(If $workItem is an instance of com.polarion.alm.tracker.model.IWorkItem):
- On Wiki Pages: $esc.escape($esc.escapeForHtmlTag($workItem.title)
- On LiveDoc (Rich Text) Pages: $esc.html($workItem.title)
If you want to use Document types and Document workflow, you need to first set up the feature in
Administration.
Procedure
1. Open the scope in which you want to enable the features (Global or some project) and enter
Administration.
Related Topics
You can create custom fields for Documents. Document custom fields are a property of each Document,
and should not be confused with Work Item custom fields. You can define Document custom fields
globally, as the default for all new Documents, for all Documents in a project, or for each Document type
defined in a given project.
• If there are custom fields defined for -- All Types -- (a type-less definition) in your Project, then they
are added to the fields defined for the Document type.
• If there is no -- All Types -- definition on the Project level but one on the Global level, then the
globally defined fields are added to all Documents in the Project.
Example
• You can create a generic-custom-fields.xml configuration that defines your Project's generic
Document types.
• Then a custom-field.xml configuration that is applicable for all Document types.
When you create a generic type Document it would contain definitions from both configurations.
Users can access Document custom fields in the Document Properties panel of the Document Sidebar in
the Document Editor.
Procedure
1. Open Administration, expand Documents and Pages, and select Document Custom Fields.
A table with the defined Document types and configured custom fields (if any) appears.
2. Click Create New in the target row. You must have administrator permissions for the target scope.
Tip
• Click Edit / Create New in the - - All Types - - row to add custom field(s) to all Documents
in the current project.
• Click Create New in the Generic row to add a custom field all Documents in all projects.
• Click Create New in a specific Document type row to only create a custom field for that
Document type.
3. Enter a unique ID, a Name (visible in the UI), and select a Type from the drop-down menu.
4. (Optional) Enter a Description. (It appears as a tooltip when users hover over the custom field.)
5. (Optional) If you want to give users the ability to select multiple values for a custom enumeration
select Multi.
Note
• Do not change the type of existing fields if Documents already contain field data of a different,
incompatible type.
• Document custom fields are copied when a Document is reused or branched.
• Users cannot reuse or branch a Document with validation errors in any of its custom fields.
• Document custom fields are always editable in reused/branched Documents.
• Custom fields in a Derived Document are ignored when the Document is updated.
• Changes to Document custom fields and custom field values are automatically tracked in the
Document History, and appear when comparing Document revisions.
This configuration provides users the possibility to classify Documents according to type. It should be
completed first before configuring Document workflow. For the Global scope, review the default types
provided by Polarion and modify the configuration if needed to provide a common denominator for all
projects. Project teams should decide whether the Global types meet their needs and if not, work with the
administrator to modify the project configuration accordingly.
If your installation does not have Document types and Document workflow set up yet, a button labeled
Set Up Types appears when you access the Document Types page. Click this button and follow the dialog
box's instructions.
Tip
Left click on and keep the mouse button pressed to drag your items into the order that you want
them.
Most of the fields should be self-explanatory. However, the following may need some clarification:
Default When selected, this type appears as the default selection in the Type field when users create a
new Document. Select this option for only one type.
Hidden If selected, the type does not appear in select lists and users cannot select it as the Document
type for new or existing Documents. This is mainly for legacy types which have been applied
to Documents in the past, but which are no longer valid and should not be applied to new or
existing Documents.
Note
Documents with a legacy type assigned to them keep that type as long as the type definition
exists in the configuration. Users can change such Documents to any of the types not marked
as Hidden in this configuration.
Note
This topic covers workflow configuration for Documents. Do not confuse this with workflow
configuration for Work Items.
Workflow controls a process to ensure that no steps are missed or skipped. Workflows for Documents
define and control process for entire Documents. Document workflow applies only to the Document, and
is separate and apart from any workflow defined for the Work Items it contains. It enables you to trace
the history of a Document's progress from inception to completion of whatever process you need for
Documents.
A workflow consists of a set of named statuses and status transitions, transition conditions and
dependencies that a Document passes through in its life cycle. For example, consider the following set
of status definitions:
If a user changes the Document's status from Draft to In Review, or Reviewed, this invokes an action
(Send to Review, for example). The action triggers a status transition, which is automatically logged
to the Document's history with details such as date, time, user invoking the action, etc. Actions may be
configured to trigger some system function — creating a linked Work Item, or clearing some field's value,
for example. The processing of a workflow action can be conditional. One or more conditions are checked
and must be satisfied before the user can invoke the action. For example, if a Document has a custom
date-time field named Draft Finished, a function could be configured to clear that field's value when the
Back to Draft action is invoked. A condition might check that the field value is not null, or is not earlier
than some specified date.
You can create and customize Document workflows and transitions in several scopes — globally (for all
projects), project-specific for individual Projects, and/or type-specific, which applies only to a specific type
of Document in a project. (Type-specific can be configured both globally and in projects.) Polarion looks for
the most specific workflow definition first and proceeds toward the most generic in the following search
sequence:
1. Configure Document custom fields — Define any fields that are needed for Documents in the scope.
If your Document workflow will not have any functions and conditions that reference Document
custom fields, you can skip this operation.
2. Configure Statuses — Determine the statuses a Document can have at various stages of its lifecycle
— Draft, In Review, Approved, for example — and create a status definition for each one in the
Statuses section of the Workflow Designer.
3. Configure Actions — Determine what actions are needed to transition a Document from one status
to another throughout your Document authoring process, and create an Action definition for each
one in the Actions section of the Workflow Designer.
Action names appear in the drop-down list of a Document's Status field in Document Properties.
The name indicates to the user what transition will take place as a result of invoking the action.
For example, an action named Send to Review might transition a Document to a status named In
Review.
You can require users to log an electronic signature when invoking any Work Item action by selecting
the check box Requires Signature column on the respective row in the Actions table.
4. Configure Functions and Conditions — This is optional, depending on whether or not any system
functions should run when an action is invoked by users, and if the running should be conditional.
(For available conditions and functions, see Workflow Conditions and Functions for Documents.
5. Configure Transitions — Now you can specify how the Document transitions from one status to
another in the Transitions section of the Workflow Designer page.
Tip
It is recommended that you create a sandbox project based on one of Polarion's default project
templates and study the Document workflow configurations for different Document types. You may
find that the default configuration meets your needs. If not, you can get a better idea of what you need
to customize and how to implement your custom workflow
When defining transitions using the Workflow Designer's Transitions matrix, it's important to keep two
things in mind:
• You are defining what transitions are allowed between any two Statuses.
• Therefore, you don't need to specify an action for every transition — just those transitions you want to
allow to occur between two Statuses.
Consider an example of a workflow for a requirements specification Document. Assume that, among
others, the statuses Draft andIn Review are defined.
It makes sense to allow transition from the Draft status to the In Review status, so at the intersection of
these two, you specify the Sent to Review action (which has already been defined in Actions).
Assuming the organization's authoring process does not allow transition directly from Draft to Reviewed, it
would not make sense to specify Send to Review, where Draft intersects Reviewed in the matrix. No action
would be specified, and the transition cell should be left empty.
For some statuses, you may want to allow more than one possible transition. For example, suppose you
have the status definitions Draft, Reviewed and Rejected. For Documents having the In Review status,
let's say there are three possibilities in the process: a stakeholder can approve the Document and give it
the Reviewed status, or decide to send it back for changes, giving it the Draft status again, or reject the
Document and give it the Rejected status. The workflow can be configured to support this process but
allowing three transitions on the In Review status.
• Transition from In Review status to Draft status via the Back to Draft action.
• Transition from In Review status to Reviewed status via the Reviewed action.
• Transition from In Review status to Rejected status via the Reject action.
Related Topics
Administrators can optionally customize the Document Properties Sidebar for LiveDocs, including or
excluding sections in a desired order, and custom form extensions. You can perform this configuration in
both globally and per project. It requires you to enter correct XML code in the editor provided on the
Administration page.
• You can configure sections for Fields, Teamcenter Share, Auto-suspect, Outline numbering, On-
demand Work Item loading, Word Round-trip template, and Remote Links.
• Extend the Document Properties Sidebar with custom sections provided by Polarion Form Extensions.
(See also: Configure Work Item Form (Editor) layout.)
• Customize the Document Properties Sidebar with a Velocity script.
Additional information and examples are provided in the embedded the Quick Help on the
Administration page.
1. Open the scope you want to configure (Global or some project) and enter Administration.
2. In Navigation, expand Documents and Pages and select Document Properties Sidebar.
3. Use the embedded XML editor on the page to enter or edit XML code for the desired configuration.
Note that projects inherit the XML from the Global configuration, which Administrators can then
modify as desired for the project.
Tip
Advanced administrators may opt to write code in an external file using a preferred XML editor, and
upload the file via the Import from File button.
After installing the Velocity form Extension, you can customize the Document Properties sidebar even
more with Velocity scripts.
The following example outlines how to use a Velocity Form Extension script to customize the Document
Properties Sidebar so that:
• When a Document has a Review status, the sidebar displays Work Items that are also in Review.
• The sidebar also displays unresolved Work Item comments for the listed Work Items.
b. Add the following to the Global/Project Configuration field and click Save.
<sections>
<section id="fields"/>
<extension id="velocity_form" label="WI Comments"
script="velocityForm/document sidebar work item comments.vm"/>
Scripting guidelines and hardcoded values for the Document Properties Sidebar
Here are a few guidelines you should follow when customizing the Document Properties sidebar using
scripts:
LiveDoc Status, Work Item Type and Work Item Status are hardcoded using variables.
#set ($docStatus="inreview")
#set ($wiType="systemrequirement")
#set ($wiStatus="inReview")
Administrators can optionally customize the Work Item Properties Sidebar for LiveDoc Documents,
including or excluding sections in a desired order, and custom form extensions. You can perform this
configuration in both globally and per project. It requires you to enter correct XML code in the editor
provided on the Administration page.
• You can configure sections for Properties, Links, Documents, Hyperlinks, and Linked Revisions.
• Extend the Work Item Properties Sidebar with custom sections provided by Polarion Form Extensions.
(See also: Configure Work Item Form (Editor) layout.)
Additional information and examples are provided in the embedded Quick Help on the Administration
page.
Procedure
1. Open the scope you want to configure (Global or some project) and enter Administration.
2. In Navigation, expand Documents and Pages and select Work Item Properties Sidebar.
3. Use the embedded XML editor on the page to enter or edit XML code for the desired configuration.
Note that projects inherit the XML from the Global configuration, which Administrators can then
modify as desired for the project.
Tip
Advanced administrators may opt to write code in an external file using a preferred XML editor, and
upload the file via the Import from File button.
Configure Signatures
Tip
See Electronic signatures for details on how to configure LDAP or other external providers to
authenticate electronic signatures.
Some organizations have a formal review and sign-off process for specifications and other documents.
Such a process can be supported in Polarion using electronic signatures, including secure signatures
compliant with common regulatory standards. This is accomplished in the Document Workflow
configuration. You can set the Requires Signature option on any configured Document workflow action
- an action such as Mark Approved, for example. Some additional parameters can be set specifying a
signature policy. It is also possible to configure a default set of invited reviewers/signers via a workflow
function with appropriate parameters.
When this option is set for a Document workflow action, the action cannot be invoked by Document users,
and the Document cannot transition to the next status in the workflow until the necessary users have
added their electronic signature, and the signature policy is satisfied. For an example, if the workflow has
an action Mark Approved which transitions the Document to the status Approved, the status transition is
blocked until invited reviewers have signed off, and the signature policy is met. If the policy requires that
all the invited signers must sign, the transition is blocked until all invited people have electronically signed
approving the transition.
Tip
Document-related signatures are U.S. CFR 21 Part 11 compliant secure electronic signatures.
For security, it is highly recommended to use the https protocol for access to Polarion when your system
is configured to use electronic signatures.
Caution
Your browser might offer to or autofill credentials in forms like e-signatures that use password fields.
Edit your browser settings or enforce the related security policies on managed computers to disable this.
You can configure any Document workflow action to require signature(s) before the status transition.
Whether or not a given workflow action requires signatures depends on the process adopted by the
project team or organization. Different stages in the process may require the signatures of a different
set of signers, which means there could be several rounds of review and sign-off before a Document is
considered as final or approved. It is the role of the Document owner or manager to decide which action
or actions require signatures, to invite people to review and sign electronically, and after all signatures are
collected, to transition the Document to the next workflow status. The administrator's role is to configure
the Document workflow according to the required process, and to configure the Requires Signature option
for the action or actions that require signatures.
Process overview
• Configure Document types. The project owner or leader should decide what types are needed for the
project. Some default types are predefined in most project templates. You can modify the default types,
add new types, or remove existing types as needed to meet the needs of the project.
• Configure Document workflows. Again, the project management should specify their process for each
Document type - what statuses each Document type can have, and the actions that can transition
the Document to them. You create a workflow configuration that applies to all Document types, and
type-specific workflows for different Document types.
• Configure workflow actions. Your project management should specify which Document workflow
actions in which Document types require signatures before the actions can be invoked by users to
transition the Document status. The following sections explain how to do this.
This topic assumes that project managers have already done the following:
Procedure
1. Log in with administrator permissions for the scope you are configuring (global, or a specific project)
and enter Administration.
2. In Navigation, expand the Documents and Pages topic and select Document Workflow.
3. Assuming that Document types have been defined as previously discussed, click the Edit button on
the row of the type you want to support signatures. (If the workflow and signature policy are the
same for all types, then edit -- All Types --.)
4. Scroll the page until you see the Actions section. This is where you configure one or more workflow
actions to require signatures.
Enable Signatures
The Actions section of the page is formatted as a table. Each configured workflow action occupies a row.
The table has a column named Requires Signature, which contains a check box. Locate the row of the
action(s) that must require signatures, and select this check box.
When you select Requires Signature, two additional fields appear in the column (see figure below).
Tip
Depending on your screen resolution, you may need to resize the Requires Signature column wider to
see these fields. Drag the column separator in the column header.
The signature policy options provide some restrictions on when the workflow action can be invoked. Hints
appear when you hover over an item in the list, which should be mostly self-explanatory. The No Policy
option is the least restrictive. It means that the Document owner can invite people to review and sign a
Document before it transitions to a new Status, but the owner can invoke the workflow action and change
the Document status whether or not anyone signs. For example, the team's process might specify that if
no one signs a specification within five business days after being invited, Documents can move forward in
the process. If some invitees do sign the Document, that is recorded in the history.
The signer role option provides and optional additional datum that may be desirable in some situations,
particularly in regulated environments. When enabled, you can specify the role of the people who sign the
workflow action. The actual value should be specified by the project owner along with the other signature
requirements. For example, if signatures are required to transition a Document from Draft to In Review, a
value such as Team Leader might be appropriate. If signatures are required to transition from In Review to
Approved, a value like Project Lead or Analyst might be specified.
This is an advanced topic requiring some familiarity with Workflow functions and conditions. In cases
where the set of people who should always be invited to sign workflow actions is static, you can configure
the action with the AddDefaultSigners function. The function selects users according to its parameter
settings, and adds them to the list of invited signers in the Signatures sidebar when the Document enters
the relevant status. The users may be specified in function parameters as a list of user IDs, or a list of user
roles, or both.
Suppose that in addition to people with the project_approver role, one or two other people should always
be added as signers for the workflow action. You can specify their user IDs in another function parameter,
and they will also be added.
Procedure
1. Before starting, make a note of the user role(s) and/or user IDs you want to specify in this
configuration.
Note
You can specify both parameters. For example, the project_approver role might add all but one or
two necessary people as default reviewers/signers. Supposing that the other people have a different
role, but not everyone with that role is needed, you can add just the IDs of the necessary users in
addition to people with the specified project role.
7. Click Close in both dialog boxes and save the Document workflow configuration.
Warning
Users with the specified roles and/or IDs are only added to the list of invitees who should sign a workflow
action. These users are not automatically notified to review and sign.
The Document owner or manager must still contact the invitees at the appropriate time and invite their
review and sign-off. (See Invite People to Sign.)
These permissions can be set in global and/or project configuration. They work for Documents and also
custom sets of Documents. They are also applicable for the dynamic role document_author.
In projects based on Polarion Project Templates, requirements specification type Documents are tied to a
permissions Custom Set named Submitted and Released Requirements Specifications. The permissions
allowing modification of this type of Document are denied for most roles. This, in effect, makes the
Document read-only when the workflow status is any except Draft.
com.siemens.polarion.collaborationNotifications.enabled=true
Note
Apache HTTP Server's minimum required version is 2.4.29 with the mod_proxy_wstunnel module
installed.
If you're updating Polarion from an earlier version, follow the instructions detailed in the
5_Required_Config_changes.txt file of the update.
(If you're using a new standalone installation of Polarion 2404 just follow the instructions outlined here.)
The default is 10, but you can configure the number of people visible in the drop-down menu before the
more... link appears.
Just add the following property to the polarion.properties file with your desired limit:
com.siemens.polarion.collaborationNotifications.maxNumberOfUsersShown=[your_li
mit_number]
Caution
If you set this limit too high, then the drop-down will extend past the end of your screen, and users
won't be able to see or click on the more... link.
Configure a port
The Collaboration Notifications feature uses a service that communicates on port 40608 by default.
You can change this port by adding the following property to the polarion.properties file.
com.siemens.polarion.collaborationNotifications.port=[your_target_port]
Tip
If you change this port, you must also:
For more information on ports, see the Connectivity table for your firewall section.
polarion.properties file on the Coordinator machine and the polarion.properties file that's accessible to
all nodes/instances. To ensure that Collaboration Notifications work correctly, Apache must be manually
configured. See the Configure Collaboration Notifications for Cluster and Multi-instance setups section for
details.
Note
Configuring Collaboration Notifications might lead to increased network traffic and might affect the
Apache service. To compensate, please set up the Apache configuration with a sufficient number of
runners.
If you experience any issues, the Collaboration Notification service can be disabled manually without
affecting Polarion.
Tip
Search for and disable the NotificationService.jar java process. (The service will automatically restart
after termination.)
Procedure
Procedure
1. Open the Task Manager and select More Details at the bottom if it is not already selected.
2. Select the Processes tab.
3. Right-click on any column header, and select Command line in the context menu if it is not already
selected.
4. In the list, find the javaw.exe process that has NotificationService.jar in the Command line column.
Note
In some cases, the process name might be different. (For example, OpenJDK Platform binary.)
Users with the requisite permissions can merge Work Item content between two Documents. A default
set of manual merge actions is available to users.
This file specifies which actions are available in the Merge sidebar for a Document that is the target of
the merge action a user wants to perform.
Administrators can modify the configuration to exclude any of the actions defined in this file.
Example
If a project's managers decide that copying a Work Item should not be allowed, the Copy the Work Item
action can be excluded in the configuration.
When excluded, the action is hidden in the sidebar, even if it would otherwise be a valid action.
Allowed actions can also be conditional, allowed only if the conditions described in the <conditions>
element of actions are satisfied.
You can find more detailed information in comments at the end of the merge/actions.xml configuration
file.
In the same configuration file, you can also control the merging of Work Item fields, specifying which
fields should and should not be included when merging Work Items.
A Manual Merge action configuration is available in both the Global and Project scope, and
requires editing the underlying XML configuration file.
You can do that either online in Administration, or offline in an XML editor, uploading the modified file
back to the Administration page.
Terminology
The merge/actions.xml file contains explanatory comments and action descriptions that use some terms
that it is important to understand.
Procedure
1. Log in with administrator permissions for the scope you want to configure, and open the desired
Repository or Project.
2. Enter Administration, and in Navigation select Documents and Pages Manual Merge
Actions.
3. Do one of the following:
a. Edit the file directly in the editor on the page and click Save.
b. Right click on the merge/actions.xml link above the editor and select Save link as to download
the file to your local system.
Edit the file in an editor, save it, click Import from file, select the file, then Save.
c. Click Import from global level to import the global level merge action configuration into the
editor then Save.
Configurable elements
If you do not want one or more of the default manual merge actions to be available to users, enclose the
<action> element(s) in an XML comment marker: <!-- -->
Example:
Tip
Comment out actions rather than delete them. If things change in the future, you can easily enable
them again by removing the comment markers.
The <conditions> element can contain one or more <condition> elements and logical operator tags
to define simple or complex conditions.
The following points are important to keep in mind when specifying conditional merge actions:
• The <conditions> element is a child of the <action> element. Only one <conditions> element is
allowed within any <action> element.
Any that appear after the first one are ignored.
• The <conditions> element can contain multiple <condition> elements.
• You can construct complex conditions by using nested <and>, <or>, and <not> tags within a
<condition> element.
• The <not> tag can contain multiple tags and the result is the same as if they were inside an <and> tag.
Therefore, the <not> tag actually works like a NAND logical operator.
• Empty <and>, <or> tags evaluate to "true". Empty <not> tags evaluate to "false".
• Unknown or invalid elements and tags, and <condition> elements having an unknown/invalid id
attribute value are ignored.
The following example shows the condition configuration format, and the possible condition ID values,
except for query-based conditions.
<action id="...">
<conditions>
<not>
<condition id="com.polarion.sourceDocumentBranchedFromTarget"/>
</not>
<not>
<condition id="com.polarion.targetDocumentBranchedFromSource"/>
</not>
<not>
<condition id="com.polarion.sourceWorkItemBranchedFromTarget"/>
</not>
<not>
<condition id="com.polarion.targetWorkItemBranchedFromSource"/>
</not>
</conditions>
</action>
If a <condition> element has one of the following values specified in its id attribute, the element can
contain a Lucene query on the respective artifact.
Example:
<action id="...">
<conditions>
<-- Work Item queries: -->
<condition id="com.polarion.sourceWorkItemQuery">type:task</
condition>
<condition id="com.polarion.targetWorkItemQuery">type:requirement
AND
status:draft</condition>
<-- Document queries: -->
<condition id="com.polarion.sourceDocumentQuery">type:generic</
condition>
<condition id="com.polarion.targetDocumentQuery">type:test-spec AND
NOT
status:draft</condition>
</conditions>
</action>
Note
• If no query is specified in the element — that is, the query is empty — the condition is ignored.
• If a query is specified, but no Work Item exists on the relevant merge side for the current merge
action, then the condition is ignored even if the query can return some results in some other context.
When you manually merge Work Items between two Documents, you may want to exert some control
over which fields are merged.
Two actions for fields are present and enabled by default in the merge/actions.xml file:
Merge Merges all supported Work Item fields. You can modify the description, or comment it out to if
All the action should not be available to users.
Fields
Merge Merges only the fields specified in the com.polarion.mergeFieldsAction in the
Some actions.xml file.
Fields
You specify the fields to be copied in <field> elements within the <fields> element. Other
fields are skipped. You can also explicitly specify field that should not be copied in <field>
elements within the <excluded-fields> element.
Note
When comparing Documents across different projects, merge actions use settings from the project
where the Target Document is stored.
Users can initiate the Automatic Merge of Work Items changes between Master and Branch Documents.
Push to Master: Work Item changes in the Branched Document are propagated to the Master
Document and a new Master Document revision is created.
Pull from Master: Work Item changes in the Master Document are propagated to the Branched
Document and a new Branch Document revision is created.
The Automatic Merge algorithm analyzes Work Item changes between the Master and Branch
Documents and consistently applies configured actions.
If no action is found in the configuration for one of the above activities, then that activity is skipped when
Automatic Merge is executed.
If several actions are found for, say, Insert, then only the first action from the XML is used.
You can use each configured action in both directions by default but can limit them to a single direction
with the following:
• direction="push": Only applies the action when you push Branch changes to the Master
Document.
• direction="pull": Only applies the action when you pull Master changes to the Branch Document.
Example:
<action id="com.polarion.duplicateWorkItemAsOverwritten" direction="push"></
action>
Tip
You can also configure conditional actions.
Default configuration
How it works:
• com.polarion.mergeFieldsAction
Merges all discovered differences for all supported Work Item fields from each Source Work Item to the
Target Work Items in both directions.
(See Fields Not Supported when Merging)
• com.polarion.duplicateWorkItemAsOverwritten direction=push
If Push to Master is executed and a new stand-alone Work Item is added to the Branch Document,
then its copy is added to the Master Document with a has_branch link to the branch's Work Item.
• com.polarion.insertLiveReference
If a new stand-alone or Referenced Work Item is added to the Master Document, its live reference is
added to the Branch Document.
If a Referenced Work Item is added to the branch with no original in the Master Document, then the
same live reference is added to the Master.
• com.polarion.unmarkWorkItem
If Work Items are deleted/unmarked in the Source Document, they are unmarked (sent to the
Recycle Bin) in the Target Document.
• com.polarion.deleteReference
If a reference to any Work Item outside of the Branch or Master Document is removed from the
Source Document, then it's also removed from the Target Document.
Note
To adjust this default behavior, you must edit the configuration XML file.
Procedure
1. Log in with administrator permissions for the scope you want to configure, and open the desired
Repository or Project.
a. Edit the file directly in the editor on the page and click Save.
b. To start a new custom configuration based on the default: Click Import Default, make your
edits, and click Save.
c. Right-click on the automatic-merge/actions.xml link (if it was saved earlier) and select Save link
as.
Click Import from File, select the edited file, then click Save.
d. Click Import from global level to import Automatic Merge's global configuration.
You can configure Automatic Merge to merge changes between the original Master Work Items and
overwritten Work Items in its Branch Document by adding the following:
<action id="com.polarion.mergeFieldsAction"></action>
• You can limit what fields you want to automatically merge by listing the ones you want to merge like
this:
<action id="com.polarion.mergeFieldsAction">
<fields>
<field id="title"/>
<field id="description"/>
</fields>
</action>
• You can exclude fields that you do not want to automatically merge by listing them like this:
<action id="com.polarion.mergeFieldsAction">
<excluded-fields>
<field id="assignee"/>
<field id="myCustomField"/>
</excluded-fields>
</action>
If a Work Item (or a referenced Work Item) exists in the Source Document but is not in the Target
Document, Polarion inserts it into the Target Document.
Note
If a user deletes/removes an item in the Target Document but it is not yet aligned with the Source
Document, Automatic Merge does not create the item again in the Target Document.
If a Work Item exists in a Target Document (and it is not a referenced Work Item), but it does not exist
in the Source Document (or is in the Recycle Bin), then one of the following Delete actions can be
applied:
• To Delete the Work Item from the Target Document and the repository (but not from the History):
<action id="com.polarion.deleteWorkItem"></action>
If a Work Item in the Target Document is a reference to a Work Item that does not exist in the Source
Document and you need to delete these references in the Target Document, add the following to your
configuration:
<action id="com.polarion.deleteReference"></action>
Note
If a user creates an item in the Target Document but it is not yet aligned with the Source Document,
Automatic Merge does not delete the item from the Target Document.
Conditions
A <condition> element with one of the following values specified in its <id> attribute can contain a
Lucene query on the respective artifact:
• com.polarion.sourceWorkItemQuery
(The <condition> value should be a Lucene query on the attributes of the Source Work Item.)
• com.polarion.targetWorkItemQuery
(The <condition> value should be a Lucene query on the attributes of the Target Work Item.)
• com.polarion.sourceDocumentQuery
(The <condition> value should be a Lucene query on the attributes of the Source Document.)
• com.polarion.targetDocumentQuery
(The <condition> value should be a Lucene query on the attributes of the Target Document.)
EXAMPLES:
<condition id="com.polarion.targetDocumentQuery">type:test-specification OR
status:draft</condition>
Note
• If the query is empty, the condition is ignored.
• If the query is defined, for example, for the Target Item, and that item is null, the condition is ignored.
You can configure the following for Documents and Pages that your users export to PDF:
Procedure
1. For the project level: Click beside the project name in the Navigation Header, click Open
Project or Project Group and select your project.
3. Expand Documents and Pages and select Configure PDF Export Template.
4. (Optional) If there's no Project configuration, you can click Import from global level and edit the
default XML.
Tip
You can edit the configuration files directly or download the Project and Global links to edit them
offline.
If you edit a file offline, click Import from file to add it back to the Polarion repository.
Caution
If you just overwrite the default siemens_export_logo.png file, you must to do it again every Polarion
update.
Procedure
1. Copy your logo to the following directory on your Polarion server: (It can be a .png, .gif or .jpg)
[POLARION_HOME]\bundled\apache\htdocs\[your_logo.png]
(By default the logo size is a width of 180px and a height of 29px, but you can resize it to suit your
needs.)
2. Open the Configure PDF Export Template for your target scope.
3. Update the logo image path.
a. Find all instances of:
5. Click Save.
A Project configuration link appears at the top.
6. Export a PDF.
Your logo should appear in the PDF export.
Note
Any margins not specified default to 20 pixels in the PDF output.
Procedure
3. Click Save.
Procedure
1. Open the Configure PDF Export Template for your target scope.
2. The scope attribute of the header and footer elements in the PDF export configuration, applicable for
projects and individual documents, lets you specify different headers/footers for the first page of an
exported PDF document. Modifiers even, odd, and skiplast can also be used.
Example:
3. Click Save.
You can manually rename Documents, Pages, Plans, Test Runs or My Polarion pages when exporting to
PDF, but can also configure Polarion so that a name is generated automatically from a mix of text, Polarion
variables, and Velocity.
Tip
• Non-ASCII file names are supported, but the following characters are not: \/:*?"<>|;`~'#[]\n\r.
• Since colons (:) are not allowed in file names, dates and times in the $[created], $[updated] and
$[generated] variables are transformed: (From: 2022-07-28 15:36 To: 20220728-1536)
• You can configure PDF file names with Polarion Artifacts tags, variables and/or Velocity.
When you export Documents, Pages, Plans, Test Runs or My Polarion pages write your custom file name
in the File Name field and click Export.
You can configure PDF file names for all Documents, Pages, Plans, Test Runs on the project or global level
in Administration.
(You can do the same for My Polarion pages but only on the global level.)
Procedure
2. Expand Documents and Pages and select Configure PDF Export Template.
3. (Optional) If there's no Project configuration, you can click Import from global level and edit the
default XML.
Tip
You can edit the configuration files directly or download the Project and Global links to edit them
offline.
If you edit a file offline, click Import from file to add it back to the Polarion repository.
4. Create the name structure that you want for the file name within the <filename> tags under the
<pdf>, <pdf-compare>, or <pdf-compare-documents> tags. You can use plain text, variables,
Velocity or a combination of any of these.
This structure becomes the new default name, and Polarion substitutes all the variables you define
with the data related to the Document, Page, Plan, or Test Run you are exporting.
(Variables must be placed between opening and closing tags. Example: <document>$
[productName]-$[productVersion]</document>)
Example
If you use the following:
<filename>
<document>$[documentTitle]_$[updated]_(rev$[revision])</document>
<richpage>Widget_type_$[documentTitle]-specification_version_$
[versionPageParameter]</richpage>
<plan>Plan_for_$[projectId]_$[generated]</plan>
<testrun>automated-tests-$[updated]</testrun>
<user>Employee-page</user>
</filename>
Tip
• See the list of Polarion Artifacts tags you can configure PDF file names for, and the variables
and/or the Velocity you can use.
• You can download this export.xml as a reference. It contains all possible examples.
(Warning: You must create Page Parameter's with the IDs identical to those in the example
before they will work.)
5. Click Save.
1. Begin exporting your Document, Page, Plan, Test Run or My Polarion Page.
2. Click Configure on the Export to PDF dialog.
The Configure the PDF Export Template dialog box appears.
3. Create the name structure that you want for the file name. (See Step 4 in the Configure PDF file
names on the Project or Global level section for details.)
4. Click Save.
<plan> The file names for PDF export of all Plans will be made up of the combination of
text, symbols, and variables defined within this tag. (Unless overridden by the specific
configuration of a particular Plan.)
<testrun> The file names for the PDF export of all Test Runs will be made up of the combination
of text, symbols, and variables defined within this tag. (Unless overridden by the
specific configuration of a particular Test Run.)
<user> The file names for the PDF export of the My Polarion page for each user will be
made up of the combination of text, symbols, and variables defined within this
tag. (Unless overridden by the specific configuration of a particular user). The value
of this tag is only used if it is defined in global administration in the specific My
Polarion Page’s configuration. Configuration in the project administration will be
ignored. This tag also does not support all variables. Only the following can be used:
$[documentName], $[documentTitle], $[revision], $[baseline], $
[generatedBy], $[generated], $[productName], $[productVersion]
The following variables can be used to automatically create custom file names for your PDF exports. The
Code column contains the string you should use.
Note
If you configure a variable that has no value, "Undefined" (or its equivalent in localized Polarion builds)
is used instead.
Page Parameters in PDF file names, headers and footers for Pages
Page Parameters can automatically be included in the file name, header or footer of LiveReport PDF
exports.
Use the same syntax as if you were using a Polarion variable. For example, $[pageParameterId].
If you have a String type Page Parameter, with the ID color and Value blue, then you could write
<richpage>Keyboard-specs_type-$[color]</richpage> in the configuration and the resulting
PDF file name of your Page would be:
Keyboard-specs_type-blue.pdf
Tip
• See Interactive Reports via Page Parameters to learn more about the types of Page Parameters
you can add.
• See Add a Page Parameter to learn how to include them.
When you have your file name generated from values of Polarion variables or Velocity outputs, then
file names can contain whitespace characters. There is an option in Polarion to have these whitespace
characters automatically replaced by a character or characters of your choosing if desired.
The spaceReplacement attribute can be used for this purpose. If you place it into the filename tag, it
will affect all Polarion artifacts (Documents, Pages, Plans, Test Runs, and My Polarion Pages). If you place
it into a specific Polarion artifact tag, then it will override the configuration of the filename tag and will
affect filenames generated for this artifact type.
Example
<filename spaceReplacement="_">
<document spaceReplacement="--">my_requirements_$[updatedBy]</document>
<richpage>widgetset_$[space]_$[createdBy]</richpage>
</filename
In this case, the resulting Document name is my_requirements_Alex--Seller.pdf and the resulting Report
(Rich Page) name is widgetset_carParts_Carl_User.pdf .
You can create or modify the global or project-scope PDF Export Configuration to include a watermark
image on the pages of exported PDF Documents and Pages.
Note
You must have permission to read or modify Documents to configure watermarks when exporting to
PDF.
Users with permission to read or modify Documents can enable or disable the Use template option
that appears in the Export to PDF dialog box and subsequently edit the export configuration to use a
watermark image if one is not yet specified, or a different watermark image of one is specified, and/or
change the opacity of a specified watermark.
Procedure
Procedure
1. If performing a project-specific configuration, open the desired project with project administrator
permissions. If performing a global configuration, open the Repository.
2. Open the Repository Browser, and navigate to .polarion/wiki/. If the wiki folder/directory does
not exist, use the Add Directory icon to add it as a sub-directory of .polarion.
3. If it does not already exist, create another new sub-directory, under .polarion/wiki/, name it
watermarks and navigate into it.
4. Create a new sub-directory for the watermark image you want to use in PDF exports for the scope
you are configuring. The name of this folder/directory is used as the watermark ID in the PDF Export
Configuration, therefore it must not contain spaces. For example, for a watermark that identifies a
document as "CONFIDENTIAL", name the folder/directory something like confidential.
5. Upload the desired watermark image file to this folder/directory using the Upload File icon of the
Repository Browser. The image should be a .PNG file with a transparent or white background, or .JPG
with white background. Be sure that the file name matches the name of the containing folder.
When you finish these steps, the Repository Browser should be showing a path to an image file that is
something like:
Procedure
1. Log in with administrator permissions for the scope you want to configure (repository or project)
2. Working in the scope you want to configure, open Administration Documents &
Pages Configure PDF Export Template.
3. If working in a project, and there is no project configuration yet, click Import from global level to
load the XML code of the global PDF Export Configuration into the XML editor of the page. This is the
basis for the project-scope configuration that you can now modify.
<pdf>
...
</footer>
<watermark id="confidential" opacity="35"/>
</pdf>
Documents will now export to PDF with the configured watermark image. A global configuration may
be overridden in individual projects with a project-scope configuration. Users with permissions to read or
modify Documents see the project-scope PDF Export Configuration when they invoke PDF export (or the
global configuration of no project-specific configuration exists), and they can modify the XML they are
presented. Their options include choosing not to include any watermark (via the Use template option in
the export dialog box).
You are not confined to using a single watermark image for all PDF exports. You can optionally set up to
use different images for different PDF export options, and create multiple image sets to support different
watermarking requirements.
You can have multiple sets of watermark images in the repository at the same time, to
be used automatically by the Exporter when end users invoke different export scenarios:
different paper size or orientation, for example. For this, you create a folder/directory
under .polarion/wiki/watermarks and populate it with appropriately named image files that
are automatically applied to the output when a user selects different export options. The repository
directory and image files should have this form: .polarion/wiki/watermarks/<watermarkId>/
<watermarkId_orientation_papersize.extension>, where folder watermarkId is a valid
Subversion repository folder name.
Within that folder you can have multiple image files using the file name convention previously mentioned,
where:
• <watermarkId_orientation_papersize.extension>
• <watermarkId_orientation.extension>
• <watermarkId.extension>
Image file names that do not correspond to the pattern are ignored — when there is only the paper
size element in the name, but no orientation, for example. Thus, confidential_portrait.png,
confidential_landscape.png, or confidential.png are valid, but confidential_A4.png is
not, and will therefore be ignored if specified in a PDF export configuration.
You might have a set of images that show the word CONFIDENTIAL in exported documents, with different
images to be applied for different PDF export options selected by users when exporting. An example of
a repository folder for this is .polarion/wiki/watermarks/confidential. In that folder you could
have the following image files:
• confidential_portrait_A4.png
• confidential_landscape_A4.png
• confidential_portrait_letter.png
• confidential_landscape_letter.png
It is possible to extend the basic concept for different requirements. For example, you could add another
folder, .polarion/wiki/watermarks/secret and populate it with another set of watermark images
— secret_portrait_A4.png, secret_landscape_A4.png, for example.
Each PDF export configuration element in Administration Documents & Pages Configure
PDF Export Template can reference one set of watermark images for each export type by a
short name which corresponds to the name of the repository folder that contains the image files. For
example: "confidential" for images contained in .polarion/wiki/watermarks/confidential/, or
I can be important to understand how watermarks are applied by Polarion. Assuming compliance with the
repository folder setup and image naming convention, Polarion automatically applies the most appropriate
watermark image from the folder represented by the id attribute when an end user executes an export to
PDF. For example, if the user invokes the export operation specifying landscape orientation and letter size
paper, Polarion looks for an image file in the repository, the file name of which contains landscape and
letter according to the aforementioned naming convention. If not found, it searches for the closest match
to the configuration.
Following the previous example, if the PDF export configuration contains <watermark
id="confidential" opacity="33"/>, then if the user invokes PDF export and selects
options for Landscape orientation and Letter paper size, Polarion will apply the image
confidential_letter_landscape.png with thirty-three percent opacity to pages in the PDF output
file. If that image is not present, will look among the remaining available images for one with the closest
match to the configuration and user-selected export parameters. If none is found in the project, Polarion
checks the global scope, and if no appropriate image is present, no watermark is displayed in the output,
and an error is written to the log files.
Tip
You can set up the export configuration discussed here in both global and project scopes. These
defaults may be overridden by a user in a document-specific configuration when exporting a particular
Document, or a set of Work Items. If no project-scope images are available, images from the global
configuration are used.
Organizations can optionally implement restrictions via the plugin API to override PDF export
configurations, placing restrictions on individual exports by individual users, to include a different
watermark in the exported documents, and/or to conform to other required policies. If such a plugin
is in use, then when a use invokes PDF export, the PDF Export Wizard dialog box shows a message:
Company policy can override these settings.
This topic lists the properties that can be specified in the PDF Export configuration to embed data values
in the header/footer of PDF documents created by exporting a Page 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".
Tip
Velocity variables can also be used in the XML configuration for PDF headers/footer configurations.
You can also change the embedded fonts if users need to export documents that contain characters from
various languages.
Procedure
Example
Linux: pdf.export.fonts.dir=file:///opt/polarion/polarion/fonts
Windows: pdf.export.fonts.dir=file:///C:/polarion/polarion/fonts
4. Generate a configuration file for PD4ML by running the following Java command from your command
line:
• Replace POLARION_PLUGINS_DIR with the location of the plugins folder in the file system of your
Polarion installation.
• Replace XYZ with Polarion release number.
• Replace FONTS_DIRECTORY with the path to your fonts.
Example
java -jar /opt/polarion/polarion/plugins/com.polarion.alm.ui_3.22.2/lib/
pd4ml.jar -configure.fonts /opt/polarion/polarion/fonts
Caution
• TTF file names can only be in ASCII characters. (Hiragana.ttf not ひらがな.ttf)
• Font names in this file must be escaped if spaces are included. (Times New Roman must be
written as Times\ New\ Roman like the example below.)
6. You must restart the Polarion server for changes to take effect.
What to do next
Example
In the example above, the Arial font is replaced in the .pdf with Gen Jyuu Gothic Monospace Bold
for Hiragana characters.
(If you do not do this embedding, Hiragana does not appear in the exported .pdf file.)
Tip
• Check the /opt/pd4browser.properties file and make sure that ttf.fonts.dir is set to the correct
font path.
Example: ttf.fonts.dir=/opt/polarion/polarion/fonts
• Make sure that the font you are using is Unicode.
Velocity variables can be used in the XML configuration for PDF headers/footers and file names for
Classic Wiki Pages, LiveDocs, Pages, Plans and Test Runs.
(This is an advanced topic that assumes knowledge of Velocity and its integration into Polarion.
Coding skills are needed for any implementation. See the Troubleshooting section for known issues
and workarounds and https://velocity.apache.org/engine/1.4/user-guide.html for additional information
about Velocity in general.)
Tip
This topic covers the Velocity variables you can use in PDF export, but you can also use Polarion
variables.
• Velocity tags for the <filename> section for Pages and LiveDocs.
• Velocity tags for the header/footer sections for Document based items: (LiveDocs, Compare,
Compare Document.)
• Velocity tags for header/footer sections of Live Reports, Plans, Test Runs and My Polarion Pages.
• Velocity tags for the header/footer sections for Wiki Pages, old Plans, old Test Runs.
• Use Test Records from the current Test Run in a header or footer.
• By using conditional logic in the configuration, you can include or exclude content of the variables or
page parameters in the header or footer of exported PDF documents.
Tip
You can view header/footer and file name Velocity examples in this Velocity.zip file.
Velocity tags for the <filename> section for Pages and LiveDocs
com.polarion.alm.shared.api.model.rp.Ric
hPage
com.polarion.alm.shared.api.model.tr.Tes
tRun
com.polarion.alm.shared.api.model.plan.P
lan
com.polarion.alm.shared.api.model.user.U
ser
$page com.polarion.alm.shared.api.model.rp.Ric Only for Live Reports (Rich
hPage Pages)
$plan com.polarion.alm.shared.api.model.plan.P Only for Plans
lan
$testRun com.polarion.alm.shared.api.model.tr.Tes Only for Test Runs
tRun
$localization com.polarion.alm.shared.api.utils.Shared
Localization
$objectFactory com.polarion.alm.shared.api.utils.veloci
ty.ObjectFactory
$transaction com.polarion.alm.shared.api.transaction.
ReadOnlyTransaction
$trackerService com.polarion.alm.tracker.ITrackerService
$projectService com.polarion.alm.projects.IProjectServic
e
$securityService com.polarion.platform.security.ISecurity
Service
$platformService com.polarion.platform.IPlatformService
$projectService com.polarion.alm.projects.IProjectServic
e
$testManagement com.polarion.alm.tracker.ITestManagement
Service Service
$date http://velocity.apache.org/tools/2.0/apidocs/org/
apache/velocity/tools/generic/DateTool.html
$math http://velocity.apache.org/tools/2.0/apidocs/org/
apache/velocity/tools/generic/MathTool.html
$number http://velocity.apache.org/tools/2.0/apidocs/org/
apache/velocity/tools/generic/NumberTool.html
$esc http://velocity.apache.org/tools/2.0/apidocs/org/
apache/velocity/tools/generic/EscapeTool.html
$alternator http://velocity.apache.org/tools/2.0/apidocs/org/
apache/velocity/tools/generic/AlternatorTool.html
$lists http://velocity.apache.org/tools/2.0/apidocs/org/
apache/velocity/tools/generic/ListTool.html
$sorter http://velocity.apache.org/tools/2.0/apidocs/org/
apache/velocity/tools/generic/SortTool.html
$mill http://velocity.apache.org/tools/2.0/apidocs/org/
apache/velocity/tools/generic/IteratorTool.html
$pageParameters com.polarion.alm.shared.api.utils.collec
tions.StrictMapImpl
$urlParameters com.polarion.alm.shared.api.utils.collec
tions.StrictMapImpl
Example
Access custom fields with Velocity:
<filename>
<document>Document_$object.fields().get("version").get()</document>
</filename>
Velocity tags for the header/footer sections for Document based items (LiveDocs, Compare, Compare
Document.)
Example
Example using the value of a Version custom field of a LiveDoc:
Velocity tags for the header/footer sections of Live Reports, Plans, Test Runs and My Polarion Pages
com.polarion.alm.shared.api.model.tr.Test
Run
com.polarion.alm.shared.api.model.plan.Pl
an
com.polarion.alm.shared.api.model.user.Us
er
$objectFactory com.polarion.alm.shared.api.utils.velocit
y.ObjectFactory
$page com.polarion.alm.shared.api.model.rp.Rich Only for Live Reports
Page (RichPages).
$pageParameters com.polarion.alm.shared.api.utils.collect
ions.StrictMapImpl
$plan com.polarion.alm.shared.api.model.plan.Pl Only for rich-page-based
an Plans.
$platformService com.polarion.platform.IPlatformService
$projectService com.polarion.alm.projects.IProjectService
$securityService com.polarion.platform.security.ISecurityS
ervice
$sorter http://velocity.apache.org/tools/2.0/apidocs/org/
apache/velocity/tools/generic/SortTool.html
$testManageme com.polarion.alm.tracker.ITestManagementS
ntService ervice
$testRun com.polarion.alm.shared.api.model.tr.Test Only for rich-page-based
Run Test Runs.
$trackerService com.polarion.alm.tracker.ITrackerService
$transaction com.polarion.alm.shared.api.transaction.R
eadOnlyTransaction
$urlParameters com.polarion.alm.shared.api.utils.collect
ions.StrictMapImpl
Velocity tags for the header/footer sections for Wiki Pages, old Plans, old Test Runs
For Wiki Pages, page parameters behave as outlined in the $pageParameters description in the
embedded Classic Wiki Help.
For example, you can include one or both of the following in some Classic Wiki Page(s):
Then, in the export configuration you could reference these as shown in the following examples:
Tip
If a Document has no value in the Title field referenced by $[documentTitle], the value of the
Document name (ID) will be used in exports.
Use Test Records from the current Test Run in a header or footer
Example
<td width="70%" align="right">Test Record Number:
$testRun.fields().records().size()</td>
Troubleshooting
• Using separators like _ or - between individual Velocity identifiers in the configuration (for example,
$me_$date) might cause issues.
<richpage>#set($spacer = "_")
$me$spacer$date</richpage>
◦ You can also use a combination of spaces and the spaceReplacement property:
<richpage spaceReplacement="_">$me text</richpage>
◦ Both examples will result in a $me_$date format without issues.
• Building a file name with an attribute directly following a Velocity identifier (for example, $me$
[updated] or $me$[documentTitle]) might cause issues.
◦ Instead, use the following workaround:
<richpage>#set($upd = "$[updated]")
$me$upd</richpage>
Polarion integrates the Highcharts library, which enables users to easily create and show various types of
simple and complex charts in LiveReport type Pages and Classic Wiki pages. NodeJS, used for preview
and PDF export of Highcharts, is also installed. By default, it starts automatically and automatically restarts
if the NodeJS process is killed.
System Administrators may optionally disable automatic start-up and restart by setting the following
system property in the polarion.properties file:
com.polarion.highchartExportServer.autoStart=false
If set this way, the System Administrator is then responsible for starting and restarting the process
manually. If not started, then users exporting pages containing Highcharts will not be able to preview
them, such pages will not export to PDF properly, and errors will be written to the log files.
To manually restart the process, issue one of the following system commands, depending on your
operating system:
The library is located under the plugin folder com.polarion.alm.ui. The path is
polarion\plugins\com.polarion.alm.ui_N.N.N\node\, where "N.N.N" is the number of your
currently installed Polarion version (e.g. "3.8.0").
There are two additional system properties for NodeJS, both optional:
During Polarion start-up, the external NodeJS process starts and binds to localhost:34567. If the
Polarion server process is killed or somehow terminates abnormally, the NodeJS process must be
terminated before restarting Polarion. The system does this automatically on restart if the system property
com.siemens.polarion.nodeJsServer.killOldProcess is set to true, which is the default
value.
If your system uses separate NodeJS processes, which would be killed by this default behavior, you can
set the value of the system property to false. If you do, then before restarting Polarion, you should
terminate the NodeJS process manually to prevent multiple instances, which can result in NodeJS failing
to start, and/or problems with binding to the port. Use one of the following command-line commands:
Configure formulas
Polarion uses NodeJS and the MathJax library to convert LaTeX mathematical formulas into SVG images.
NodeJS starts automatically by default, and automatically restarts if the NodeJS process is killed.
System Administrators can disable the automatic start and restart of NodeJS by setting
the com.siemens.polarion.nodeJsServer.autoStart=false system property in the
polarion.properties file.
Caution
If set to false, administrators must start or restart the process manually. If it is not started, then users
will not be able to see formulas and they will be replaced with a warning image in both Polarion and
exported artifacts. (PDF or Microsoft Word.) An error message will also be logged.
To manually restart the process, issue one of the following system commands in:
[POLARION HOME]/polarion/plugins/com.polarion.alm.ui_[version]/node/bin
Windows:
Linux:
Note
You may have to change the file's ownership.
During Polarion start-up, the external NodeJS process starts and binds to localhost:34568. If
the Polarion server process is killed or somehow terminates abnormally, the NodeJS process must
be terminated before restarting Polarion. The system does this automatically when restarted if the
com.siemens.polarion.nodeJsServer.killOldProcess system property is set to true. (The
default.)
If your system uses a separate NodeJS processes that would be killed by this default behavior, you can
set the value of the system property to false. If you do, then before restarting Polarion, you should
terminate the NodeJS process manually to prevent multiple instances, which can result in NodeJS failing to
start, or problems with the port binding. Use one of the following command-line commands:
Windows:
Linux:
pkill -f node
Configure Notifications
Related Topics
Configure Notifications
Polarion can send email notifications to users when changes occur to objects in the system. Notification
events are triggered when such changes take place.
Change examples
• A new Work Item is created, or an existing Work Item is updated — its status, assignee, or approval
state changes, for example.
• A new user is created.
• A new Document is created, updated, or commented in a project.
• A build finishes or fails.
• A Page with Watchers set updated or deleted.
Notification events have targets, which represent some user or an aggregation of users who are to
receive emails when the event occurs. For example, by default a status-changed event has a target
current-author representing the author of the Work Item. Therefore, when a change in the Work Item's
status triggers the event, a notification is sent to the user who created the item. Some targets represent an
aggregation of users. The all-watchers target encapsulates all users who have a Watch set on a Work Item
at the time the event occurs.
Note
READ permission required:
If a user does not have the READ permission on the artifact (Work Item, Space, Page, or
Document), they do not receive update notifications for it.
Limitations:
• For Custom Artifact Sets, you can only restrict email notifications via permissions for Work Items that
are not part of a Document.
• You cannot use field-level artifact permissions to restrict email notifications.
Events can have multiple targets. For example, the status-changed event might be configured to also have
targets all-watchers and all-voters in addition to the current-author target. If the same user happens to
be included in multiple targets for the same event, only one notification is sent to that user.
Note
If a user is part of the aggregation of a target that is included for an event, and also in the aggregation of
another target that is excluded in the same event, the user will not receive notifications triggered by that
event.
For example, if the workitem-linked event is configured to include the all-watchers target, and exclude
the all-commenters target, and User A is included in the aggregation of users for both those targets,
User A will not receive a notification when the workitem-linked event occurs.
The default notification scheme is designed to be sufficient for many organizations, but may not be exactly
what yours needs. For example, you may want to reduce the overall number of notifications going across
your network, or add targets, or change default targets of some events. Therefore, the notification scheme
is configurable.
Enable notifications
Before Polarion can send email notification to users, it is necessary to enable the Notifications feature,
specifying the SMTP server and other parameters. Because this is typically done during the platform
installation and initial configuration process, details are provided in the Deployment and Maintenance
Guide. It can be found in the Polarion section of Support Center. On Windows systems, the installer
presents a screen for enabling notifications, specifying the email server, and other configuration settings.
Once you have email notifications enabled for your installation, you can proceed to customize the
configuration for the notifications feature as described in later in this topic.
Basic notification properties are configured in the global scope of each Polarion instance. Notifications
can be configured both globally for each instance, and in individual projects to override the global
configuration.
Procedure
1. Log on with administrator permissions for the scope you want to configure.
3. In Navigation, expand Notifications. If you are working in the Global Administration scope, the
following navigation nodes appear:
Settings Global configuration for some basic settings related to properties of emails sent
by the system.
Events and Global configuration of targets for notification events
Targets
Layouts Global configuration for the layout of email messages for notifications related
to Work Items.
If you are working in the project scope, only the Events and Targets and Layouts nodes appear,
providing access to the project-scope configuration for these items. Settings in the project scope
override the same settings in the global configuration.
4. Select Events and Targets if you want to update a Notification.
Tip
See Notification Events and Targets for more information on the options that appear there.
6. Scroll to the top and click Save when you are done.
The Settings page of the Notifications topic provides fields where you can specify a prefix for the subject
line, and an email address to be used as the sender address in outgoing notification emails. Refer to the
Quick Help text embedded in the page for information and examples.
The Notification Events and Targets page provides table of the notification events currently configured
for the scope in which you are working. You can add more events to, or remove events from the
The objective here is to decide which events occurring in the scope should trigger notifications, and —
just as importantly — which events you do not want triggering notifications. You must also decide which
users and aggregations of users, represented by targets, should receive notifications as a result of the
events you decide to include in the configuration. You should make sure to include all the desired events
in the configuration, and remove any events for which you don't want any notifications triggered. For each
event you include, you need to be sure that the target or targets include all the users who should receive
notifications when the event occurs.
Reference information explaining the events and targets is embedded on the Notification Events and
Targets page where you configure the settings. (You may need to scroll the page to see it). In particular,
you will need to understand how actual users are represented by each target in order ensure that no one is
left out who needs to receive a notification. Target names are descriptive and should help you with this.
The Events and Targets table is important to understand in order to successfully customize the
notifications configuration. Each row in the table represents a notification event. The name of the event
appears in bold-face type in the Event column.
Tip
Events, targets, and their names are predefined and cannot be changed.
The targets currently configured for each event are listed in a tabular format in the Targets column. Each
target occupies a row in a sub-table embedded in each event row. The last sub-table row enables you to
add another target to the event using a select list of targets. You can remove existing targets listed in this
sub-table by clicking the icon on the desired row. You can add multiple targets using the icon to create
a new row in the sub-table for an additional target.
You can add events or remove events by adding or removing rows in the Events and Targets table.
Remove an event row using the icon in the row's Actions column. The last row in the table enables you
to add an event, using a drop-down list of events to specify which event. (You will probably need to scroll
down to see this row.) You can add multiple events using the icon.
• The icon in the Actions column is disabled in the project scope when there is no project-scope
configuration, and the project is using the global configuration. You need to create a project-scope
configuration using the Create button that appears above the Events and Targets table when you are
working in project scope.
• Advanced settings are hidden by default. Click the Show Advanced Settings button in the page toolbar
to show or hide these settings. Advanced settings provide event-specific data fields, and event-specific
fields for properties of email messages generated in response to the event . For details, see the
embedded Help on the Notification Events and Targets page.
• The set of events and the set of targets are predefined in the system. You cannot add items to, or delete
items from these sets, or modify their names.
Notification Layouts provide a way to customize the layout of email notification messages about new
and updated Work Items. A Notification Layout specifies what fields are displayed in notification email
messages, and how those fields are arranged. Notification Layouts can be configured in both global and
project scopes.You can create unspecific layouts that apply to all Work Item types, and type-specific layouts
that apply to one specified Work Item type.
In the default global configuration there are some predefined layouts ,which you can optionally customize.
You can create your own custom layouts in global or project scope using the default XML code of these
layouts as a starting point. To actually use a customized Notification Layout, you must specify its name in
the Layout field of relevant Work Item events on the Notification Events and Targets page. (Click Show
Advanced Settings on that page to expose the field.)
The Notification Layout Configuration page that appears when you create a new layout, or edit an
existing layout, provides an embedded XML editor that you can use to configure the layout without leaving
your browser. Embedded Help on the page provides extensive comments on the various elements and how
to structure them to achieve the desired layout.
Procedure
1. Log on with administrator permissions for the scope you want to configure.
2. Open the repository or project you want to configure and enter Administration if you are not already
there when you log on.
Users can individually opt out of receiving email notifications by selecting the Disable Notifications option
on their user account page. As an administrator, you may need to find users who have done this. You can
run this check in Global Administration or in individual projects.
Procedure
1. Log on with administrator permissions for the scope you want to check.
2. Open the scope you want to search (repository, or the desired project), and in Navigation select
User Management Users.
A table of all users in the current scope appears on the page.
3. In the Search field of the Users page, enter this search string disabledNotifications:true and
click Search.
The table of users is filtered to show only those users who have checked the Disable Notifications
option in their user account page.
Tip
Instead of searching, you can optionally sort the table of users on the Disabled Notifications column by
clicking on that column header.
Notification attachments are embedded in target user emails and link to the revision of the Polarion
artifact that an attachment was added to or removed from.
Before they are embedded into the Notification, attachment preview images are compressed based on
height and width to maintain their aspect ratio.
The following properties in the polarion.property file determine how much they are compressed:
• com.polarion.notification.maxAttachmentWidth
Configure the maximum width of an attachment in a Notification.
Default Value: 1024
The attachment's width is set to this (in pixels) if its original exceeds this limit.
• com.polarion.notification.maxAttachmentHeight
Configure the maximum height of an attachment in a Notification.
Default Value: 768
The attachment's height is set to this (in pixels) if its original exceeds this limit.
You can also configure whether Target users can view a preview of the embedded attachments.
• com.polarion.notification.maxAttachmentSize
It determines whether to display a preview based on the size of the compressed image.
Default Value: 2.0
(In megabytes)
(If set to 0, no limit is placed on attachment size and no previews are generated for attachments.)
A preview is shown if the attachment size (or aggregate size for multiple attachments) is less than 2 MB.
If the attachment size exceeds the set limit, Polarion inserts a placeholder instead.
Note
• If the property's value is set to 50, and someone adds or removes multiple attachments to or from an
artifact, previews are displayed for attachments until the limit is exceeded.
• The Open in Polarion links below attachment placeholders do not point to the direct attachment
link. They point to the revision where the attachment was added to or removed from the Work Item,
Report, or Document.
(For Documents, it leads to Polarion's revision comparison where users can see precisely when
and where the attachment was added or removed.)
You may decide that you want to use SSL to provide additional security for Polarion, especially in cases
where you are going to set up single sign-on authentication and/or automate the creation of new user
accounts. This topic discusses how to configure SSL when using the Apache web server installed and
configured when you installed Polarion. If you installed Polarion on Windows, everything you need to set
up SSL access to Polarion is bundled in the Polarion installation, including default configuration files. On
Linux systems, everything needed is usually included in Linux distros.
Warning
SSL might be required by some SAML or OAuth 2 authentication providers.
SSL access is configured by standard means in Apache. The only Polarion-specific configuration for SSL is to
specify HTTPS protocol for the Subversion repository.
In-depth documentation on using SSL with Apache is beyond the scope of this Help. For a real
understanding of everything described here, and to understand how to actually make an Apache web
server secure, it is recommended that you refer to some more specialized resources on the subject. See
topic Additional resources for links to some that can help you get started.
Warning
Leave the SSLSessionCacheTimeout value at 300 in Apache’s configuration settings to avoid
potential broken pipe exceptions.
Configure SSL
Unless you have disabled the Resource Traceability feature, which is enabled by default, you will have to
import a certificate into your Polarion Java TrustStore.
If your organization does not have a TrustStore, importing to the Java Keystore will also work. See Import a
Certificate to the Java Keystore. It must also be done for self-signed certificates.
Procedure
a. Windows: [POLARION_HOME]bundled\apache\conf\httpd.conf
3. Search for the line containing: LoadModule ssl_module modules/mod_ssl.so and remove
the comment marker (#).
(Uncommenting this line activates the SSL module.)
4. Search for the line containing Include conf/extra/httpd-ssl.conf and remove the leading
comment marker (#).
5. (Optional) Deactivate unencrypted HTTP traffic. Edit the .conf file.
a. Linux: (See Step 2 for the .conf location on your Linux distribution.)
b. Windows: [POLARION_HOME]\bundled\apache\conf\httpd.conf
Find the line Listen 80 and add a comment marker # at the beginning, leaving the line as:
#Listen 80.
6. Set up the certificate file for SSL. Open the following file in a text editor and search for
SSLCertificateFile. Change the path to point to the certificate file.
a. Linux: See Step 2 for the path for your Linux distribution.
b. Windows: [POLARION_HOME]\bundled\apache\conf\extra\httpd-ssl.conf
Example (Windows): SSLCertificateFile
"C:\Polarion\bundled\apache\conf\certificate.pem"
7. Set up the key file in SSL. Search for SSLCertificateKeyFile in same file as Step 6 and change
the path so that it points to the certificate key file.
Example (Windows): SSLCertificateKeyFile
"C:\Polarion\bundled\apache\conf\privateKey.key"
8. If you use a certificate that is not from an authority trusted by Java, (like a self-signed certificate),
Import the certificate to the Java Keystore.
9. Change the Subversion (SVN) protocol setting in Polarion system configuration properties. To do
this, edit the polarion.properties file, and change the following property:
(Replace http with https and remove the reference to port 80, if present.)
If the above property is not already present in the file, add it on a new line.
Note
You will need to reindex Polarion whenever you change the base.url. Be sure to plan for server
unavailability during the process, which can be lengthy. See Index and reindex for information
and paths to the launcher scripts.
Open the httpd-ssl.conf file in a text editor, add ServerName [YOUR SERVER NAME] and save your
changes.
Example: ServerName polarion.dev.ourdomain.com
The general, Apache2 configuration continues to evolve and varies depending on the distribution. See the
links below for updated, distribution specific, instructions.
• Debian-based Distributions
• Redhat-based Distributions
• SUSE-based Distributions
Unless you've disabled the Resource Traceability feature that's now enabled by default, you will have to
import a certificate into your Polarion Java TrustStore.
-Djavax.net.ssl.trustStore
If your organization does not have a TrustStore, importing to the Java Key store will also work. See Import
a Certificate to the Java Keystore. It must also be done for self-signed certificates.
Polarion-specific settings
Procedure
1. If you are using a certificate that is not from an authority trusted by Java, import the certificate to the
Java keystore, as described in Import a Certificate to the Java Keystore.
On Linux, the keytool will be located in the same directory as the version of Java used by Polarion at
$JDK_HOME.
2. Change the Subversion (SVN) protocol setting in Polarion system configuration properties. Edit
the polarion.properties file, and change the following properties, replacing http with https and
removing references to port 80, if present:
Note
You will need to reindex Polarion any time you change the base.url.
ServerName polarion.dev.ourdomain.com
Additional resources
Tip
If you don't have the desired certificates as files, you can extract them from the Java Keystore with the
following command:
• You are not using a SSL certificate that is signed by an authority trusted by Java.
Use of a trusted certificate is preferred and recommended because using an untrusted certificate,
such as a self-signed certificate, will cause web services communication to fail with the
SSLHandshakeException error.
• Before making the switch from OpenJDK 11 to OpenJDK 17.
The information is important only if you are not using a SSL certificate that is signed by an authority
trusted by Java. Use of a trusted certificate is preferred and recommended because using an untrusted
certificate, such as a self-signed certificate, will cause web services communication to fail with the
SSLHandshakeException error. If you do opt to use an untrusted certificate, then you must import
it into the Java keystore.
The general import procedure is described below, followed by examples for Linux and Windows.
Procedure
Windows example:
The following command should be written as a single line. It must be run as Administrator. If the Java
paths on your system contain spaces, they must be contained in a pair of double straight quotes, as
shown.
Depending on your operating system and version, additional command parameters may be necessary.
Keytool Commands
keytool -help
Warning
This procedure requires restarting the Polarion server. Users will lose access temporarily, and may lose
unsaved work. Before restarting, alert your users to save their work and wait until Polarion is running
again.
Polarion's Subversion repository is accessible via HTTPS protocol when SSL is configured for Apache. To set
up secure access:
Procedure
1. Use a text editor to open the system configuration properties file polarion.properties.
2. Locate the repo property.
By default, the value is set to something like repo=http://localhost:81/repo/ or http://
polarion.yourdomain.com/repo/.
3. Change the protocol in the repo property from http to https.
4. Check to be sure that the logon credentials are correct for HTTPS access.
5. Save your changes and restart the Polarion server.
Configure Building
Scope(s): Project
This topic discusses configuration and usage of Polarion's basic build management features. It explains
how to quickly get started with several common project build types:
Additional information for more complex and custom building with Polarion are covered in: Advanced
build management .
Tip
Administrators can Disable builds or Calculation Jobs for security reasons by adding the following
properties to the polarion.properties file:
A default build definition called _default is sufficient for most builds. When you click Finish in the
Create Build wizard, the build will start.
Procedure
As mentioned above, you should be able to accept the defaults. If you want build reports to be
updated after the build, select Update reports together with the build.
There is essentially no difference between a simple Maven 2 project and multiproject when it comes
to building with Polarion. The only thing which must be assured is that every module in a Maven 2
multiproject is recognized by Polarion.
As with Maven projects, Ant builds are also auto-recognized by Polarion - it looks for the file build.xml.
The Polarion build artifact's name is either the value of the name attribute of the Ant project, or the simple
string ant.
If there are multiple Ant builds in one project, additional steps must be performed to distinguish between
them (because Polarion will assign each build artifact the same artifact ID). Suppose the project's structure
looks like this:
trunk
|--- build.xml
|--- sources
|--- scripts
|--- release_build.xml
You can make Polarion recognize the different builds by modifying the file.polarion/builder/
artifacts.xml (for the project, not the global scope):
Setting the auto-recognition attribute to false disables auto-recognition for the entire project (since
it is not needed in this case). Because the second Ant build file is not named build.xml and is not located
Procedure
If base location is not explicitly specified, then it is the project's location (or trunk folder if the build
artifact was auto-recognized and such a folder exists).
Unless Maven builds, Ant builds (and all other types) do not deploy anything by default to anywhere.
Only basic information is deployed to BIR. To be able to deploy more things, a build descriptor must
be used. The default build descriptor can be extended with this (contents of the project-level repository
file .polarion/builder/descriptors.xml):
<descriptors>
<descriptor>
<deploy>
<copy dir="dist" includes="*.jar" todir="results" label="jar
files"/>
</deploy>
</descriptor>
</descriptors>
This will deploy all jars which appear in the dist folder to BIR folder results with label jar files. The
name, and a link to this deployment, will be visible in the build's detail.
Note
The <descriptor> element could have a name attribute with the name of the descriptor. There
could be descriptors with different names for different types of builds. See the advanced topic on build
descriptors for more information.
trunk
|--- build
|--- build.sh
|--- src
Let's also suppose that developers run builds by going into the build directory and executing make all.
Since it is not possible to call external scripts directly, a simple shell script must be created in the build
folder namedbuild.sh:
#!/bin/sh
make "$@"
.polarion/builder/artifacts.xml file:
<artifact>
<type>shell</type>
<location>trunk</location>
<workdir>build</workdir>
<executable>build/build.sh</executable>
<arguments>all</arguments>
</artifact>
Now when a build runs, trunk is downloaded to local disk (the location parameter) and make
all is run (by invoking executable with correct arguments) from the build directory (the workdir
parameter).
This is essentially the same as makefile builds. The main difference is that executable files, batch files,
and shell scripts not stored in the repository must be called by some special script that is stored in the
repository.
Procedure
1. Scheduled builds
2. Integration builds
Scheduled builds are those builds which run at regular intervals without manual intervention. Integration
builds are builds in which only updates of source code committed since the last build are downloaded from
repository, and intermediate results of the last build (like compiled classes) are still available.
The following is an example of an integration build that runs every hour. You would define such a build in
the jobs configuration file /.polarion/jobs/schedule.xml. (See Configure the Scheduler for more
information on this configuration file and working with scheduled jobs.)
You can include some information about Work Items in build results by configuring Work Item Reports for
builds. The Work Item reports configuration for builds is available for both repository and for each project.
Use the following procedure to access the configuration.
Procedure
1. Log on with administrator permissions for the scope you want to configure (Repository or project).
2. Open the repository or project you want to configure.
3. If necessary, enter Administration by clicking the Administration link in the tool view of
Navigation.
4. In Navigation, expand Building and select Work Item Reports. The Work Item Reports
administration page loads in your browser.
This configuration is performed by editing the workitem_reports.xml configuration file. You can either edit
the file in the text editor provided on the administration page, or download it, edit locally, and upload the
edited file back to the portal using the controls provided on the administration page.
The <workitem-report> element in the configuration file enables listing of some Work Items in the
build preview and notification. A typical usage is to list the Work Items resolved since the previous build.
You can configure several Work Item reports, each corresponding to one <workitem-report> element
in the configuration. Each report will show as a section in the build preview and notification, below the
Build Results section.
The configuration file contains extensive comments and an example of a typical configuration in
comments. Please refer to the embedded comments for documentation about the available elements
and attributes.
This topic covers Polarion build management configuration and customization in more depth for those
who have more complex building setups than those described in Basic build management.
Note
Availability in Polarion Requirements and Reviewer:
This feature is also available in Polarion Requirements , but it is hidden in the default configuration.
The topic can be shown in Navigation by changing the Navigation topics configuration. For more
information, see Configure Interface Views.
Scope(s): Project
Build Artifacts
Build artifacts are the smallest buildable entity. They are comprised of resources (usually source code and
support files). Multiple build artifacts may share the same resources.
One project may contain zero, one, or more build artifacts. Their definition is stored in the
artifacts.xml configuration file.
Procedure
1. Log on with administrator permissions for the scope you want to configure.
2. Enter Administration.
3. Open the scope you want to configure (global/repository, project group, or project.) See Access
Projects for details.
a. Edit the file directly in the editor on the page and click Save.
Edit the file in an editor, save it, click Click Import from file, select the file, then Save.
Tip
If you modify the artifacts.xml file directly in the repository, you’ll need to click Reload Artifacts for
your changes to take effect.
The basic format of the configuration file can be found in the Administration reference topic: Build
configuration file format. Please refer to it as necessary.
Local deployment space is a place where a build artifact is downloaded before building. Let's consider an
example with the following source repository structure:
Assume that pom.xml is written as if sources were in a folder named src in its directory. This definition can
be used:
<artifact>
<type>maven2</type>
<location>trunk</location>
<resources>
<resource source="sources" target="build/src" recurse="true"/>
<resource source="build/pom.xml" target="build"/>
</resources>
</artifact>
Each artifact is identified by its group id. The same convention is used with Java package names .
For example, com.polarion.sample, and artifact id a hyphen-delimited name, such as sample-
demo . These IDs are usually based on the artifact itself, or are specified in the above configuration.
Artifacts also have their label, version and list of source directories (for source-based calculations).
This topic describes the types of build artifacts supported in Polarion build management. Currently
supported types are:
• Maven 2
• Ant
• Shell (batch/executable invocation)
Maven 2
Additional elements:
Label and source directories are determined from POM file. Note that if POM file is of type pom and it
defines modules, then those modules must be build artifacts themselves.
Note
Instead of embedded Maven, you can use external Maven, either the one bundled with Polarion
distributions, or any other installation you have. This is not enabled by default during upgrades (only for
new installations), but is strongly encouraged to do by placing following into the global /.polarion/
builder/build.properties file: polarion.build.maven.executor=maven2
Ant
Additional elements:
<sourceDirectories>
<!-- default is based on artifact id -->
<label>LABEL</label>
<!-- default is 1.0.0 -->
<version>VERSION</version>
Shell
Batch/executable invocation
Additional elements
<executable>EXECUTABLE_LOCATION_RELATIVE_TO_BASE_LOCATION</executable>
<!-- may be omitted ->
<arguments>ARGUMENT1 ARGUMENT2 ...</arguments>
<!-- default is executable's directory -->
<workdir>WORKING_DIRECTORY_RELATIVE_TO_BASE_LOCATION</workdir>
<!-- default is derived from project's location -->
<groupId>GROUP_ID</groupId>
<!-- default is "ant" -->
<artifactId>ARTIFACT_ID</artifactId>
<!-- may be omitted -->
<sourceDirectories>
<sourceDirectory>
SOURCE_DIRECTORY_LOCATION_RELATIVE_TO_BASE_LOCATION
</sourceDirectory>
... <sourceDirectory> ...
<sourceDirectories>
<!-- default is based on artifact id -->
<label>LABEL</label>
<!-- default is 1.0.0 -->
<version>VERSION</version>
Note
The term build definition may appear in the portal user interface. It refers to build descriptor as
described in this topic.
Descriptors are configured in the file .polarion/builder/descriptors.xml. You can configure build
descriptors in both the global scope, and per project. These are merged if necessary. Here is an example of
a build descriptor:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
xsi:schemaLocation="http://polarion.com/schema/Builder/Descriptors">
<!-- no name and "_default" are equal -->
<descriptor name="NAME">
<!-- may be omitted -->
<artifacts>
<artifact>
<!-- if id ends with "*" then the given prefix is searched for;
default value is "*" -->
<groupId>GROUP_ID</groupId>
<!-- if id ends with "*" then the given prefix is searched for;
default value is "*" -->
<artifactId>ARTIFACT_ID</artifactId>
</artifact>
... <artifact> ...
</artifacts>
<!-- may be omitted -->
<build>
<properties>
<PROPERTY_NAME>PROPERTY_VALUE</PROPERTY_NAME>
...
</properties>
</build>
<!-- may be omitted -->
<deploy>
<!-- includes and excludes may be omitted,
default value for defaultexcludes is true -->
<copy|move todir="TARGET_DIRECTORY" label="LABEL_FOR_BUILD_REPORT"
dir="SOURCE_DIRECTORY" includes="INCLUDES_PATTERN"
excludes="EXCLUDES_PATTERN" defaultexcludes=
"USE_DEFAULT_EXCLUDES_TRUE_OR_FALSE">
... <copy|move> ...
<item todir="TARGET_DIRECTORY" label="LABEL_FOR_BUILD_REPORT"
name="ITEM_NAME" />
... <item> ...
</deploy>
</descriptor>
... <descriptor> ...
</descriptors>
Warning
Usage of <move> or move in <deploy> should be used with caution. It can fail depending on operating
system, file system and whether BIR is on the same file system/volume/disk as the data folder. It is also
not possible to combine more deployments whose sources are on the same path. Generally, the move
feature should be used with care and only if necessary due to storage space or performance reasons.
Descriptors are attached to all build artifacts which match a given group and artifact IDs (or all if
<artifacts> is omitted). There could be two different descriptors with same name attached to different
artifacts.
There is always one default build descriptor named _default which simply runs a build and deploys it to
BIR (linked from the build report) data produced by Maven 2. This default descriptor can be overridden by a
descriptor with the same name (or nameless).
In <deploy> tags includes, excludes and default excludes are the same as in Ant (see http://
ant.apache.org/manual/CoreTypes/fileset.html for more information).
There is only one deploy item supported for build artifacts of type maven2: default, which will deploy
all files produced by a Maven 2 build (stored in target directory).
It could be said that a build artifact describes what is built, and build descriptor (definition) describes how
it is built. Reality is a bit more complicated than this, because build artifacts also define how the build
should go. So the more correct view is that a build artifact says what is built (type, identification, repository
resources), and what tools are used and their basic configuration (both defined by type-dependent files),
while a build descriptor says how these tools are configured (by build properties) and what are the build
results (that is, BIR deployment).
Build properties
Built-in properties
The following properties are set by the system before a build and cannot be changed:
Standard properties
Warning
Please note that setting this property to true may cause failed builds or calculations, because local
Maven repository is not safe for concurrent modifications, and calculations use it by default.
The default deployment repository is used if the POM file does not define the
<distributionManagement> section.
All build properties are reflected as properties accessible by standard ways in Maven (including properties
controlling behavior of various plugins like compiler, etc.)
Ant-specific properties
For example:
polarion.build.ant.taskdef.1.resource=net/sf/antcontrib/antlib.xml
polarion.build.ant.taskdef.1.classpath=ant-contrib-1.0b3.jar
All build properties are reflected as properties accessible by standard ways in Ant.
Shell-specific properties
Working directory
• Working directory of the job related to the build (its location is visible in build's log).
• Base location (in local deployment space = after the download from repository).
• Base directory of Maven 2 (accessible by Maven property basedir).
• Current working directory (called "current user directory" or "cwd" by various platforms).
Base location is either somewhere under the job's working directory or inside the shared local deployment
space (if it is an integration build).
Base directory of Maven 2 is always the directory where pom.xml was downloaded (or the build file for Ant
builds, or executable for shell builds - Maven is used internally for execution of those). It is under the base
location.
If embedded Maven is used, then the current working directory is always the same as the working
directory of Polarion (usually directory from which Polarion was run). Otherwise, if external Maven is used
(which is the default), then the current working directory is the same as the base directory of Maven 2.
For shell builds, the current working directory can be changed, regardless of which Maven is used, to any
directory relative to base location by specifying the <workdir> element in the build artifacts definition.
Note
Because auto-recognition (and detection of changes to build artifacts and related configuration) is a
potentially resource intensive operation, it is disabled by default.
polarion.startup.disable.artifacts.auto.recognition
polarion.startup.disable.artifacts.change.detection.
• Clean start (or recognition requested from UI) and there is no artifacts.xml present in the configuration.
• Clean start (or recognition requested from UI) and artifacts.xml is present in the configuration with
auto-recognition set to true. (The default setting.)
Polarion can also auto-recognize artifacts of types maven2 (searches for pom.xml) and ant (searches for
build.xml). Files are searched to a maximum of three folders depth, starting from project's location or
folder trunk within project's location (if there is one, then it is taken as base location for all artifacts found).
Source directories are automatically determined for maven2, and heuristics is used for ant (heuristics is
name-based, not content-based).
If no artifact is auto-recognized, but source directories are found, then special artifact of type auto is used.
This type is not intended for building. Rather, it allows source-based reports to work on unknown data.
Eclipse Projects
Eclipse projects can be built using the Eclipse PDE Maven Plugin (see https://www.mojohaus.org/
versions-maven-plugin/) which wraps the Eclipse PDE headless build process automation. For details on
usage see the Usage section of https://www.mojohaus.org/versions-maven-plugin/. In short, one Maven
project is created for one Eclipse project (which may contain multiple features and plugins) which must be
rigorously structured (all the features in one folder and all the plugins in second folder).
If your repository structure is different than the one required by the Eclipse PDE Maven Plugin, you can
adjust build artifact's resources to make the structure upon the build execution. For example consider this
repository structure (all under the trunk folder):
folderA
|--- plugin1
|--- plugin2
|--- feature1
folderB
|--- plugin3
|--- feature2
pom.xml
features
|--- feature1
|--- feature2
plugins
|--- plugin1
|--- plugin2
|--- plugin3
pom.xml
<artifact>
<type>maven2</type>
<location>trunk</location>
<resources>
<resource source="folderA/plugin1" target="plugins/plugin1"
recurse="true"/>
<resource source="folderA/plugin2" target="plugins/plugin2"
recurse="true"/>
<resource source="folderB/plugin3" target="plugins/plugin3"
recurse="true"/>
<resource source="folderA/feature1" target="features/feature1"
recurse="true"/>
<resource source="folderB/feature2" target="features/feature2"
recurse="true"/>
<resource source="pom.xml" target=""/>
</resources>
</artifact>
Maven 1 Projects
Polarion is able to automatically recognize source code from simple Maven 1 projects whose layout
adheres to recommended conventions (with source code in src/main/java. Such build artifacts have
their artifact ID (visible in Create New Build wizard) set to auto. The system should be able to compute
source code metrics for this artifact, but please note that source code detection is entirely heuristic and
may not properly detect source code. It is highly recommended to migrate Maven 1 projects to Maven 2
and not to rely on this source code detection feature.
There is no direct support for building of Maven 1 projects. However it is possible to call Maven 1 from the
command-line as any other tool (see information on build artifacts of type Shell).
Migrate to Maven 2:
Migration from Maven 1 to Maven 2 is usually very straightforward. Most projects can be converted simply
by copying project.xml as pom.xml with a few changes (all these changes apply to elements directly
under top-level <project> element):
• remove <groupId>...</groupId>,
• change <package>...</package> to <groupId>...</groupId>,
• add <packaging>jar</packaging>.
For more information see the official Guide to Moving from Maven 1.x to Maven 2.x on Maven's site.
There is also a possibility to convert a Maven 1 project to a Maven 2 project by using the Maven 2
One Plugin. Issue command mvn one:convert in the same directory as project.xml. This will not only
convert project definition files, but the plugin also tries to convert any Maven 1 reports to their Maven
2 counterparts. Please note that the conversion is not 100%, but mostly it works. Be sure to update
artifacts.xml or issue build artifacts auto-recognition after checking the converted project back in to
repository.
Branched artifacts
There is explicit support for branched artifacts. Artifacts from a branch are handled the same as trunk
artifacts. Because Polarion identifies artifacts (from one project) by their group and artifact IDs, and it
is fairly common to have branched artifacts with same group and artifact ID but different version, some
work-around must be done in order to be able to build trunk and branched artifacts. There are two
possibilities:
Maven-specific information
This topic provides some advanced information related to building with Maven 2.
Maven profiles
It is sometimes required to distinguish between running the builds on a developer's machine and running
them inside Polarion. For this, Maven's concept of profiles can be used (more information is available at
http://maven.apache.org/guides/introduction/introduction-to-profiles.html). There are several ways to
define profiles, but here is the use of global profiles defined in c:\polarion\maven\settings.xml
or /opt/polarion/maven/settings.xml. Just add new profiles to the ones already there:
<profile>
<id>development</id>
<properties>
<somePathProperty>FOLDER_ON_DEVELOPERS_MACHINE</somePathProperty>
</properties>
<id>polarion</id>
<properties>
<somePathProperty>FOLDER_ON_POLARION_MACHINE</somePathProperty>
</properties>
</profile>
If developer runs this in stand-alone Maven with argument -P development, then the build will
have a property somePathProperty pointing to a folder on developer's machine. If it is run inside
Polarion, and build property polarion.build.maven.active.profiles is set to polarion, then
the somePathProperty property will point to a folder on the Polarion server.
Maven proxy
To minimize connections to the central Maven repository (by other means than by using potentially
dangerous polarion.build.shared.local.repository), it is recommended to use Maven proxy.
Once you have the proxy installed, just edit C:/Polarion/maven/settings.xml and add a new
<mirror> section. For example:
<settings>
<localRepository>C:/Polarion/data/maven-repo</localRepository>
<mirrors>
<mirror>
<mirrorOf>central</mirrorOf>
<id>central-mirror</id>
<name>Mirror of Central Repo</name>
<url>http://PROXY_HOST:PROXY_PORT/PROXY_PREFIX/repository</url>
</mirror>
</mirrors>
<profiles>
<profile>
<id>polarion-bundled</id>
<repositories>
<repository>
<id>polarion-bundled</id>
<url>file:///C:/Polarion/maven/repository</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>polarion-bundled</id>
<url>file:///C:/Polarion/maven/repository</url>
</pluginRepository>
</pluginRepositories>
</profile>
<profile>
<id>polarion-shared</id>
<repositories>
<repository>
<id>polarion-shared</id>
<url>file:///C:/Polarion/data/shared-maven-repo</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>polarion-shared</id>
<url>file:///C:/Polarion/data/shared-maven-repo</url>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>polarion-bundled</activeProfile>
<activeProfile>polarion-shared</activeProfile>
</activeProfiles>
</settings>
Update to https
If you use Maven to build your software and it generates errors like the following (because it needs to
download artifacts from the Maven central repository), you must update to https:
To update the Maven configuration to use an https based repository, you must add a mirror repository to
the settings.xml file in the Maven folder.
On Linux: /opt/polarion/maven/settings.xml
On Windows: c:\Polarion\maven\settings.xml
Procedure
<settings>
...
<mirrors>
<mirror>
<id>https-central</id>
<url>https://repo1.maven.org/maven2</url>
Note
If the Maven build log gives an error about connecting to https://repo1.maven.org/maven2 then
do the following:
Procedure
Note
Must be on a single line.
See https://medium.com/@gustavocalcaterra/debugging-yet-another-ssl-tls-error-the-
trustanchors-parameter-must-be-non-empty-7dd9cb300f43 for more information.
Maven repositories
Note
The bundled Maven repository has been changed and no longer includes any third-party libraries. As a
result, calculations and builds might start contacting Maven's central repository on the Internet. If the
Polarion server has no connection to the Maven central repository then you might consider employing a
Maven repository manager. You should use it first by another Polarion server connected to the Internet,
(so that this mirror contains all necessary artifacts) and then switch over to the disconnected Polarion
server. (See Apache's Maven Documentation for more information on repository managers).
There is no difference (except for additional configuration which can change the behavior) between
running stand-alone Maven 2 tool and running a build with external Maven.
Embedded Maven is significantly different because it is a development version in a frozen state, and is
carefully balanced to work with bundled plugins. Using it for builds is discouraged.
Maven 2 is a core piece of the Polarion build management system. All builds and calculations are routed
through it. Embedded Maven is version 2.1, bundled external Maven is version 2.0 (installed at C:/
Polarion/maven/distribution).
If something fails and it is not clear why, then it is recommended to go to the working directory of the
build's job, find pom.xml (even if the build was not a Maven build) and see what is inside that could cause
something to go wrong.
When tests are run during a standard Maven build, they can be automatically imported as a Test Run when
properties in .polarion\builder\build.properties are set. It is possible to fill some Test Run fields
from an xUnit file name using regular expressions (regex).
Scheduled builds
Tip
You can also schedule a remote Jenkins build.
Build is run with the access rights of the system user (defined in polarion.properties in the login
property). So make sure that this user has repository access to all sources.
Integration builds
Integration builds are builds which are deployed to one shared local deployment space. This results in a
faster deployment phase, because only changes are downloaded from the repository, and the build phase
is faster because results of previous build are still in place. Please note that calculations share the same
shared local deployment space. Integration builds which must wait for others have status WAITING.
Configure Repositories
By default, Polarion has its own integrated Subversion repository that stores Polarion artifacts like Work
Items, Documents and Test Runs that's configured when you install Polarion in Linux or Windows. After
installation, you can configure Polarion to use one or more external repositories in addition to the SVN
repository installed and/or configured during installation of Polarion.
Caution
• If you manage your development code base(s) in the same (default) SVN repository, then you don't
need to configure an additional repository. (But if you plan to store additional files, especially large
files like binaries, you should store them in an external repository. If you try to store them in Polarion's
Subversion repository, it can adversely affect system performance.)
• You must configure external repositories if you manage your code base(s) in a repository of another
supported source code management system.
• The default SVN repository is always used by Polarion to store Work Items and other Polarion data. If
you have source code for the project in this repository as well as in an external repository, then after
adding an external repository to the configuration, you must explicitly add the Default repository back
to the project configuration. If you don't, then users will not be able to link source code revisions
made in the default repository to Work Items.
To do this, begin adding a new repository by clicking the Add below button on the configuration
page, select Default in the Provider list, and save the change.
When your Polarion project is configured, users can link an external repository revision to a Polarion
Work Item, either automatically by including the Work Item ID in the commit comment, or manually
in the Linked Revisions table of a Work Item. Revisions from an external repository appear in the same
Linked Revisions table as revisions from Polarion's own SVN repository in the Work Item editor. They are
differentiated visually by an icon.
Tip
• Are revisions located on the local SVN repository.
It is possible to configure more than one external repository and you have two methods you can choose
from:
◦ Supports only Commit Traceability (but can be combined with Direct Polling for Resource
Traceability).
Supported Repositories: Git, GitHub, GitLab, Bitbucket Cloud, Bitbucket Server and Subversion
(SVN).
Resource Traceability is a Polarion feature that gives users the power to link source code assets
semantically. (Link Work Items directly to the source code function, method, or variable that implements
them.)
Note
If you're moving a Project to another location within your repository and it has a configured
connection to an external repository, you must reenter the external repository's credentials in the
Project you moved. ( Administration Repositories Configuration.)
Tip
Polarion does not automatically refresh the index after updating the external repository configuration.
In this case, we recommend that you delete the existing external repository configuration and create
a new one with the updated information. When you add a new external repository, the new data is
automatically added to the index through a background process. Otherwise, a full reindex is required
and results in some downtime.
The Clustering feature enables you to run Polarion on multiple servers, either physical, virtual, or a
combination. The topography can be set up to host multiple servers running on separate machines each
with its own Polarion repository, and/or multiple machines all accessing a single Polarion repository.
(Polarion servers on any node can optionally be configured to access external repositories, as described
above.)
Special installation and configuration procedures beyond the scope of Help documentation are required to
set up a clustered multi-server environment. These are covered fully in the Deployment and Maintenance
Guide, available in the Polarion product center of Support Center.
Tip
Additional external repositories can be integrated into Polarion by installing an extension.
Related Topics
Direct Polling
Direct polling makes change traceability available by default. All you need to do is configure external
repositories in Polarion Administration.
The direct polling method is based on the principle that each Polarion node polls each external repository
regularly for new commits, even if there is no change. If they find new commits, the data is indexed
to Polarion for further linking to Work Items, either automatically by including the Work Item ID in the
commit comment or manually by linking commits via the Revision Picker.
You can configure the polling frequency with the following property in the polarion.properties file:
com.polarion.repository.pollingPeriod
Tip
We recommend switching to the ERA solution if commit traceability is an important part of your process.
If commit traceability is just a supplementary feature and you are not worried about the number of
connected repositories and branches or the amount of processed data, you can stick with the default
direct polling method.
• When using SSH keys on Linux, make sure that you place them in the folder /opt/polarion/data/.ssh.
• When using SSH keys on Windows, make sure that you place them in the
C:\WINDOWS\system32\config\systemprofile\.ssh folder if the Polarion service runs under the local
system.
• Values for the user name and password for each repository are automatically encrypted and stored in
the User Accounts Vault.
• You can adjust the time interval for Polarion to poll external repositories for changes. The default
interval is 5000 milliseconds. If you want to change it:
1. Open the system configuration properties file polarion.properties in a text editor.
2. Find the line starting with com.polarion.repository.pollingPeriod. If it is not already
present in the file, add it on a new line.
3. Specify a value in milliseconds.
Example: com.polarion.repository.pollingPeriod=10000
4. Save the changes.
Note
The change does not take effect until you restart the Polarion server.
Subversion
Procedure
1. Log on with administrator permissions and enter Administration on the project level.
Note
Use slashes, if using file path in Root URL, even on Windows
8. (Optional) Enter a User Name. (Valid user name of the SVN repository user which will be used for
polling.)
9. (Optional) Enter the User Password: (The password of the user specified in the User Name field.)
10. Retype the User Password.
11. (Optional) Enter a View URL. (Points to overall information about the revision.)
12. (Optional) Enter a View Location URL. (Points to historical content of changed file.)
13. (Optional) Enter a Location Diff URL. (Points to change diff of changed file.)
14. (Optional) Enter a Traceable Resource Location URL. (Points to the position of the linked resource.)
Git
Procedure
1. Log on with administrator permissions and enter Administration on the project level.
Note
The Git repository must already exist on the local file system before it can be used by Polarion.
There are two possible scenarios:
a. If the Git repository is on the same machine as the Polarion server and it is not a clone of
any other repository, then Local Repository should point to its local folder (including the .git
folder unless it is a bare repository), and Master MUST be checked.
b. If Git repository is somewhere else, then that repository must be manually cloned to the same
machine as Polarion server, Local Repository should point to its local folder (including the .git
folder unless it is a bare repository), and Master MUST NOT be checked.
These online resources may be useful: http://git.github.io/git-reference/creating/ and https://
help.github.com/articles/fetching-a-remote/
9. (Optional) Enter a View URL. (Points to overall information about the revision.)
10. (Optional) Enter a View Location URL. (Points to historical content of changed file.)
11. (Optional) Enter a Location Diff URL. (Points to change diff of changed file.)
12. (Optional) Enter a Traceable Resource Location URL. (Points to the position of the linked resource.)
GitHub
Procedure
1. Log on with administrator permissions and enter Administration on the project level.
GitLab
Note
Polarion supports native GitLab source code traceability for GitLab 9.0 or higher.
Procedure
Caution
If there are already revisions indexed by a GitLab repository, then if the branch field of the GitLab
repository configuration is cleared, Polarion will not be able to resolve the indexed revisions, and
will log errors — every time a Work Item Editor is opened, for example. To resolve this, an
administrator must reindex the Polarion system, which will remove the old revisions from the
index.
Bitbucket Cloud
Note
The following instructions are only for the cloud version of Bitbucket.
For on-premise Bitbucket deployments, follow the Configure Bitbucket Server instructions.
Procedure
1. Log on with administrator permissions and enter Administration on the project level.
9. Enter a User Name. (Valid user name of the Bitbucket repository user that to be used for polling.)
10. Enter the App password in the User Password field. (As of March 1st 2022 only the Bitbucket app
password is valid.)
The App password can be created in Bitbucket's security configuration:
Bitbucket Server
Note
The following instructions are only for on-premise Bitbucket deployments.
Procedure
1. Log on with administrator permissions and enter Administration on the project level.
Parameter Reference
The following parameters can customize the View Location URL and View Location Diff URL fields.
Example
• ID: widgetsExtension
• Name: Extra Widgets for Polarion ALM
• Root URL: http://example.com/repo
• View URL: http://example.com/polarion/svnwebclient/revisionDetails.jsp?
rev=$revision$
• View Location URL: http://example.com/svnwebclient/fileContent.jsp?
url=$locationEscaped$&pegrev=$headRevision$&crev=$revision$
• View Location Diff URL: http://example.com/svnwebclient/changedResource.jsp?
url=$locationEscaped$&rev=$revision$&action=$action$
• View Traceable Resource Location URL: http://example.com/svnwebclient/
fileContent.jsp?url=$locationEscaped$&rev=$headRevision$&line=$position$
ERA Solution
By default, Polarion uses Direct polling for repository change traceability, but we also created a service
that aggregates data from connected external repositories: The External Repository Aggregator Service
(ERA). The new ERA solution for Change Traceability provides a scalable way of connecting all your
external repositories to your data in Polarion for cases where the direct polling method is insufficient.
ERA uses Apache Kafka as an intermediary Data Exchange tool. Schematically the solution looks like this:
Polarion nodes still have the same polling logic, but unlike the direct polling method, only a single point is
polled. (Apache Kafka accumulates the commit metadata for all configured external repositories. This data
is sent there by the ERA service. )
ERA acts as a single point of contact with the external repositories, which - combined with the Hook/
Webhook/Git Hook approach - decreases the number of queries made between Polarion and the connected
repositories by up to 97%.
ERA also does health polling of the external repositories. (In case some commits were not received either
due to network issues or if hooks are not configured). But it does it much less frequently than the direct
polling method. (Every 60 minutes by default, but you can reconfigure it.)
ERA can monitor all branches in all your repositories, while the direct polling method is unsuitable for
monitoring more than a handful of repositories and branches simultaneously.
ERA can also automatically pick up new branches created in the connected repositories by matching the
Branch ID with a preconfigured RegEx expression.
Tip
If you want to start using the ERA Solution, see the ERA Solution for Change Traceability document for
details on downloading, installing, and managing the ERA Solution.
(Help only contains information on how to configure existing or new repositories and webhooks once
the ERA Solution is installed.)
Caution
If you already have an external repository configured in Polarion, skip right to Repositories already
configured in Polarion.
Note
• Polarion supports native GitLab change traceability for GitLab 9.0 or higher.
• The ERA solution requires that you follow the repository naming convention outlined at:
https://git-scm.com/book/en/v2/Git-on-the-Server-Getting-Git-on-a-Server
(This is especially true for bare repositories.)
• To connect Git and SVN repositories, they must be checked out on the same machine as the External
Repository Aggregator service.
(See Git clone on Aggregator machine section of the ERA Solution for Change Traceability
document.)
• If you have already configured a GitHub repository, you must update the value for the API URL field.
(The ERA solution uses the real GitHub URL there instead of the API URL.)
New Repositories
Git
Procedure
Note
Additional details are described in the Quick Help on the Repository Configuration page in
Polarion.
Caution
Use only numbers and letters for the Local Repository path. Special characters are not supported.
The Git repository must already exist locally on the same machine as the External Repository
Aggregator Service.
(See the Git repository on Aggregator section of the ERA Solution for Change Traceability
document on Support Center for details.)
There are two possible scenarios:
a. If the Git repository is on the same machine as the External Repository Aggregator Service
and it is not a clone of another repository, then Local Repository should point to its local folder.
(This includes the .git folder unless it is a bare repository.)
Caution
Then Master MUST also be selected.
b. If the Git repository is somewhere else, it must be manually cloned to the same machine as
External Repository Aggregator Service.
The Local Repository should point to its local folder. (This includes the .git folder unless it is a
bare repository.)
Caution
In this case, Master MUST NOT be selected.
Note
A Secret webhook key is generated automatically for the new repository when you save the
configuration. As soon as it's generated, it is visible in UI. The secret value can then be copied and
used when you configure webhooks in the external repository.
15. Enter a Default branch. Specify the branch that the other branches should be merged to.
16. Enter a Branch Filter. Type a regular expression to select the branches for this repository.
• Supported characters for the Default branch and Branch Filter fields include:
The a-z, A-Z, 0-9, -, ., _ values separated by commas. (Branches with unsupported characters in
their names are skipped from processing.)
• When using regular expressions in the Branch Filter field, use the correct RegEx syntax.
You can test your RegEx syntax at https://regexr.com or https://regex101.com.
(Do not use '/' as a RegEx boundary at the beginning or end of the Branch Filter field value.)
Example
◦ .+
Returns any branch with a name. (A non-empty string.)
◦ ^branch.$
Returns branches with names that start with 'branch'.
◦ .branch.
Returns branches with names that contain 'branch'.
◦ ^[A-Za-z0-9_-]{3,16}$
Matches branches with names that contain a combination of 3 to 16 of the following
characters: A-Z, a-z, 0-9, _, or -.
• Click Show Matches to see what branches matched your regular expression.
◦ The button is disabled for nonexistent or unsaved RegEx configurations.
◦ After saving a RegEx, please, wait a couple of minutes before checking the results.
(Polarion must retrieve the list of branches from the repository using ERA and apply the RegEx to
them, and this can take a few minutes.)
◦ If no matched branches appear, then no branches matching the RegEx exist in the external
repository, or the search is still in progress, and you should check back a little later.
◦ Only branches with names that contain the supported characters listed above are displayed and
processed.
18. Add a customized version of the following code snippet to the Work Item Form (Editor) layout so
that the Merge Requests section appears in Work Items.
<extension id="GitLabExtension" label="Merge Request Label"
sourceBranchNameField="[name of custom field with working branch name]"
targetBranchNameField="[name of custom field with target branch name]"/>
The label is customizable. If you do not already have custom fields for a source branch name
and a target branch name (optional), you'll need to create some.
Tip
See Work Item Form (Edit) layout for details on how to add the code snippet to the and create
custom fields for branch names.
GitHub
Procedure
1. Log on with administrator permissions and enter Administration on the project level.
7. (Optional) Enter a Name. (The name to display in Polarion for the repository.)
8. Enter an API URL. Use a real GitHub URL instead of an API URL.
(For example: https://github.com for a public GitHub and <https://github.companyname.com> for an
Enterprise GitHub instance.)
9. Enter the Access Token. (The personal access token you can generate in GitHub under
Settings Personal access tokens Generate new token.)
10. Enter the Repository Owner. (The owner of the repository you want to connect to.)
11. Enter the Repository Name. (Name of the repository you want to connect to.)
Note
A Secret webhook key is generated automatically for the new repository when you save the
configuration. As soon as it's generated, it is visible in UI. The secret value can then be copied and
used when you configure webhooks in the external repository.
12. Enter a Default branch. Specify the branch that the other branches should be merged to.
13. Enter Branch Filter. Type a regular expression to select the branches for this repository.
• Supported characters for the Default branch and Branch Filter fields include:
The a-z, A-Z, 0-9, -, ., _ values separated by commas. (Branches with unsupported characters in
their names are skipped from processing.)
• When using regular expressions in the Branch Filter field, use the correct RegEx syntax.
You can test your RegEx syntax at https://regexr.com or https://regex101.com.
(Do not use '/' as a RegEx boundary at the beginning or end of the Branch Filter field value.)
Example
◦ .+
Returns any branch with a name. (A non-empty string.)
◦ ^branch.$
Returns branches with names that start with 'branch'.
◦ .branch.
Returns branches with names that contain 'branch'.
◦ ^[A-Za-z0-9_-]{3,16}$
Matches branches with names that contain a combination of 3 to 16 of the following
characters: A-Z, a-z, 0-9, _, or -.
• Click Show Matches to see what branches matched your regular expression.
◦ The button is disabled for nonexistent or unsaved RegEx configurations.
◦ After saving a RegEx, please, wait a couple of minutes before checking the results.
(Polarion must retrieve the list of branches from the repository using ERA and apply the RegEx to
them, and this can take a few minutes.)
◦ If no matched branches appear, then no branches matching the RegEx exist in the external
repository, or the search is still in progress, and you should check back a little later.
◦ Only branches with names that contain the supported characters listed above are displayed and
processed.
GitLab
Procedure
Note
A Secret webhook key is generated automatically for the new repository when you save the
configuration. As soon as it is generated, it is visible in the UI. The secret value can then be copied
and used when you configure webhooks in the external repository.
13. Enter a Default branch. Specify the branch that the other branches should be merged to.
14. Enter Branch Filter. Type a regular expression to select the branches for this repository.
• Supported characters for the Default branch and Branch Filter fields include:
The a-z, A-Z, 0-9, -, ., _ values separated by commas. (Branches with unsupported characters in
their names are skipped from processing.)
• When using regular expressions in the Branch Filter field, use the correct RegEx syntax.
You can test your RegEx syntax at https://regexr.com or https://regex101.com.
(Do not use '/' as a RegEx boundary at the beginning or end of the Branch Filter field value.)
Example
◦ .+
Returns any branch with a name. (A non-empty string.)
◦ ^branch.$
Returns branches with names that start with 'branch'.
◦ .branch.
Returns branches with names that contain 'branch'.
◦ ^[A-Za-z0-9_-]{3,16}$
Matches branches with names that contain a combination of 3 to 16 of the following
characters: A-Z, a-z, 0-9, _, or -.
• Click Show Matches to see what branches matched your regular expression.
◦ The button is disabled for nonexistent or unsaved RegEx configurations.
◦ After saving a RegEx, please, wait a couple of minutes before checking the results.
(Polarion must retrieve the list of branches from the repository using ERA and apply the RegEx to
them, and this can take a few minutes.)
◦ If no matched branches appear, then no branches matching the RegEx exist in the external
repository, or the search is still in progress, and you should check back a little later.
◦ Only branches with names that contain the supported characters listed above are displayed and
processed.
16. Add a customized version of the following code snippet to the Work Item Form (Editor) layout so
that the Merge Requests section appears in Work Items.
<extension id="GitLabExtension" label="Merge Request Label"
sourceBranchNameField="[name of custom field with working branch name]"
targetBranchNameField="[name of custom field with target branch name]"/>
The label is customizable. If you do not already have custom fields for a source branch name
and a target branch name (optional), you will need to create some.
Tip
See Work Item Form (Editor) layout for details on how to add the code snippet to the and create
custom fields for branch names.
Bitbucket Cloud
Note
The following instructions are only for the cloud version of Bitbucket.
For on-premise Bitbucket deployments, follow the Configure Bitbucket Server instructions.
Procedure
1. Log on with administrator permissions and enter Administration on the project level.
13. Enter a Default branch. Specify the branch that the other branches should be merged to.
14. Enter Branch Filter. Type a regular expression to select the branches for this repository.
• Supported characters for the Default branch and Branch Filter fields include:
The a-z, A-Z, 0-9, -, ., _ values separated by commas. (Branches with unsupported characters in
their names are skipped from processing.)
• When using regular expressions in the Branch Filter field, use the correct RegEx syntax.
You can test your RegEx syntax at https://regexr.com or https://regex101.com.
(Do not use '/' as a RegEx boundary at the beginning or end of the Branch Filter field value.)
Example
◦ .+
Returns any branch with a name. (A non-empty string.)
◦ ^branch.$
Returns branches with names that start with 'branch'.
◦ .branch.
Returns branches with names that contain 'branch'.
◦ ^[A-Za-z0-9_-]{3,16}$
Matches branches with names that contain a combination of 3 to 16 of the following
characters: A-Z, a-z, 0-9, _, or -.
• Click Show Matches to see what branches matched your regular expression.
◦ The button is disabled for nonexistent or unsaved RegEx configurations.
◦ After saving a RegEx, please, wait a couple of minutes before checking the results.
(Polarion must retrieve the list of branches from the repository using ERA and apply the RegEx to
them, and this can take a few minutes.)
◦ If no matched branches appear, then no branches matching the RegEx exist in the external
repository, or the search is still in progress, and you should check back a little later.
◦ Only branches with names that contain the supported characters listed above are displayed and
processed.
Bitbucket Server
For the cloud version of Bitbucket, follow the Configure Bitbucket instructions.
Procedure
1. Log on with administrator permissions and enter Administration on the project level.
Example
◦ .+
Returns any branch with a name. (A non-empty string.)
◦ ^branch.$
Returns branches with names that start with 'branch'.
◦ .branch.
Returns branches with names that contain 'branch'.
◦ ^[A-Za-z0-9_-]{3,16}$
Matches branches with names that contain a combination of 3 to 16 of the following
characters: A-Z, a-z, 0-9, _, or -.
• Click Show Matches to see what branches matched your regular expression.
◦ The button is disabled for nonexistent or unsaved RegEx configurations.
◦ After saving a RegEx, please, wait a couple of minutes before checking the results.
(Polarion must retrieve the list of branches from the repository using ERA and apply the RegEx to
them, and this can take a few minutes.)
◦ If no matched branches appear, then no branches matching the RegEx exist in the external
repository, or the search is still in progress, and you should check back a little later.
◦ Only branches with names that contain the supported characters listed above are displayed and
processed.
Subversion (SVN)
Procedure
1. Log on with administrator permissions and enter Administration on the project level.
Note
Use forward slashes (/) in the Root URL file path. (For both Linux and Windows.)
12. Enter the View Location URL. (The URL that points to the change diff of a changed file.)
13. Enter the View Location Diff URL. (The URL that points to the change diff of a changed file.)
14. Enter the View Traceable Resource Location URL. (The URL that points to the position of the linked
resource.)
Note
A Secret webhook key is generated automatically for the new repository when you save the
configuration. As soon as it's generated, it is visible in UI. The secret value can then be copied and
used when you configure webhooks in the external repository.
What to do next
Note
As soon as the repository is configured in Polarion, its configuration is sent to Apache Kafka. The
External Repository Aggregator Service then fetches revisions and puts them in Apache Kafka where
they are available for Polarion during the indexing process.
Tip
See the Parameter Reference topic for parameters that you can add to the View URL, and View
Location URL and View Location Diff URL fields.
You must configure a repository in Polarion before you can follow the steps below:
Caution
• For the ERA Solution, you must configure Default Branch values (the branch that the other branches
should be merged to), for all previously configured repositories.
• Update any repository configurations via the Polarion Administration UI.
• If you update the repositories.xml file directly, access-related parameters (Access Tokens, Usernames,
User Passwords, etc.) are lost.
You must share all existing repository configurations with the External Repository Aggregator Service
before it starts fetching revisions.
Tip
If you want to start using the ERA solution but anticipate extensive load times for your Polarion nodes
(when indexing all external revisions), see the Start Apache Kafka storage from scratch section of the
ERA Solution for Change Traceability document on Support Center. (You do not need to change the
connectionId or run an Apache Kafka clean-up the first time it is run.)
Note
To use an existing GitHub configuration with the ERA solution, you must change the API URL in the
GitHub configuration.
(The ERA solution requires that you put a real URL (for example, ) in the API URL field.)
Procedure
What to do next
Note
The ERA Service restarts its Apache Kafka Stream application every time it gets a new configuration. So,
if you have multiple configured external repositories and Resend all Configurations, expect a 5 - 10
second delay for each before the ERA service starts fetching external revisions.
Tip
Indexing can take a while. If you want a faster way to set things up and you do not have many
repositories but a lot of revisions, you can delete all repository configurations manually and reconfigure
them.
Caution
If you delete a repository configuration and reconfigure it based on the instructions above, make sure
you use the same ID.
(Otherwise, you will lose revisions that were manually linked in the initial configuration.)
Tip
Polarion does not automatically refresh the index after updating the external repository configuration.
In this case, we recommend that you delete the existing external repository configuration and create
a new one with the updated information. When you add a new external repository, the new data is
automatically added to the index through a background process. Otherwise, a full reindex is required
and results in some downtime.
Configure webhooks
If you already have a repository configured in Polarion, but you want to use webhooks to get new
revisions from them, you can do the following in Polarion, then configure the webhooks in the external
repository.
Note
• Getting new revisions through webhooks is the primary role of the ERA solution, but there is
also a health polling function. Every hour the External Repository Aggregator Service polls all
configured repositories to check for new revisions that were not sent by webhooks. If a new branch
(matching the External Repository configuration in Polarion) is added on the repository side, and
the Aggregator Service gets a webhook about a commit in this branch, it is not processed until the
next time health polling is run. The list of branches that the Aggregator Service is aware of for the
repository is updated during health polling, and it can also process webhooks for its commits.
• The ERA solution doesn't support webhooks on a Bitbucket Server. Only polling is available.
You can change the default polling period setting of 60 min by adding the following to the application.yml
file:
aggregator:
pollingIntervalMinutes: 30
Do the following for any repository that you want to use webhooks for:
Caution
If you have already generated a Secret, you can regenerate it, but then must also change the webhook
settings in the external repository. If you do not, you will not be able to get new revisions via webhooks
from that repository.
Procedure
2. Click Edit beside the repository that you want to configure webhooks for.
The Repository Configuration screen appears.
3. Click Generate New beside the Secret field.
4. Confirm the Secret key generation when the confirmation dialog box appears.
A Secret is generated and changes are saved automatically.
The updated configuration is sent to Apache Kafka, and the External Repository Aggregator Service
starts using it.
5. Once a Secret is generated (or regenerated) you must configure webhook settings in the external
repository.
What to do next
Tip
Save any configuration updates before you click Generate New or the changes will be lost.
In an external repository
In a GIT repository
The ERA solution uses a post-receive Git hook to notify the Aggregator Service about commits
pushed to the external repository. This post-receive Git hook is a custom script that runs on the server.
You must place your bare origin repository on the ERA service host and put the post-receive script in
the hooks folder within this bare origin repository, or the Git hooks will not work correctly. You must also
have a Git clone on the ERA service machine.
(See the Git clone on Aggregator machine section of the ERA Solution for Change Traceability
document on Support Center.)
Note
The Git post-receive script is provided in the ExternalRepoAggregatorService-latest.zip file.
Caution
The ERA solution does not work correctly if you have multiple cloned repositories of the original
repository. (You must only have one origin and one cloned repository.)
#Put the secret key generated in Polarion for your repository here.
secret="your_secret_key"
• repositoryDir: The same path you configured in Polarion. (Local path to your Git clone repository.)
• serviceURL: The URL of the Aggregator Service.
• secret: The Secret key (token) generated inside Polarion.
Warning
You cannot use two post-receive Git hooks in the same repository.
If you already use one, paste the script provided in the ExternalRepoAggregatorService-latest.zip file into
your existing post-receive hook.
In a GitHub repository
Tip
Explore GitHub's official webhook documentation to learn how they work in GitHub.
Procedure
1. Navigate to the webhooks page by going to GitHub choose your repository Settings
Webhooks.
2. Click Add webhook.
3. Put the hostname where the Aggregator Service is running into the Payload URL field:
(http://aggregator-host-name.com:9000/github)
Note
The Aggregator address must belong to the same network as the external repository or be publicly
accessible.
In a GitLab repository
Tip
Explore GitLab's official webhook documentation to learn how they work in GitLab.
Procedure
1. Navigate to the webhooks page by going to Gitlab your project’s Settings Webhooks.
If you specify a secret token, it will be sent with the webhook request in the X-Gitlab-Token HTTP
header. Your webhook endpoint can check that to verify that the request is legitimate.
2. Put the hostname where the Aggregator Service is running into the URL field:
http://aggregator-host-name.com:9000/gitlab
Note
The Aggregator address must belong to the same network as the external repository or be publicly
accessible.
3. Paste the token generated in Polarion for the target repository in the Secret Token field.
Note
Currently, we recommend that you don't enable SSL Verification.
Procedure
1. From Bitbucket, open the repository that you want to add the webhook to.
2. Click the Settings link on the left.
3. Click the Webhooks link on the Settings page.
4. Click Add webhook to create a webhook for the repository.
5. Enter a Title with a short description on the Add new webhook page.
6. Put the hostname where the Aggregator Service is running into the URL field.
(http://aggregator-host-name.com:9000/bitbucket)
Note
The Aggregator address must belong to the same network as the external repository or be publicly
accessible.
What to do next
Tip
Visit Atlassian's Manage webhooks support page for more information.
In an SVN repository
Note
The SVN webhook script is provided in the ExternalRepoAggregatorService-latest.zip file, but you need
to configure it.
The ERA solution uses a post-commit SVN webhook to notify the Aggregator Service about the commits
pushed to the external repository. This post-commit SVN webhook is a custom script that runs on the
server. You must place it in the hooks folder within the origin repository.
Warning
You cannot use two post-commit SVN webhooks in the same repository. If you already use one, paste
the script provided by the Polarion team into your existing post-commit hook.
Procedure
1. Open the post-commit.bat file template and specify the following parameters:
REM Put the URL of the SVN repository root here. (Must be the same as
in Polarion)
SET location=http://<hostname>
REM Put the secret key generated in Polarion for your repository here.
SET secret="your_secret_key"
• location: The same URL to the SVN repository that you configured in Polarion
• serviceURL: The URL and port of the External Repository Aggregator Service.
• Secret: The Secret key (token) generated inside Polarion.
Tip
Keep your secrets safe. Store them in a secure location.
• curlPath:
The path to the Curl utility that sends data over the network.
If your Windows 10 build is 17063 or later, cURL is in C:\Windows\System32\curl.exe
If it is not installed, download it from https://curl.haxx.se/windows/.
Caution
The SVN hook script does not recognize environment variables. You must include the full path in
this property.
curl_path=C:\windows\System32\
2. Put the updated post-commit.bat into the /hook folder in the SVN repository.
It will run after a commit and send a revision to the External Repository Aggregator Service.
Encoding:
To send UTF-8 characters via the hook script, you must enable Unicode UTF-8 for worldwide language
support in Windows.
Procedure
4. Click on Region.
5. Click on the Administrative tab.
6. Click Change system locale...
7. Select Beta: Use Unicode UTF-8 for worldwide language support and click OK.
Procedure
1. Open the post-commit file template and specify the following parameters:
#!/bin/bash
#Put the repository location URL. (Must be the same as in Polarion.)
location="http://<hostname>"
#Put here your secret key generated in Polarion for your repository.
secret="your secret key"
• location: The same URL to the SVN repository that you configured in Polarion
• serviceURL: The URL and port of the Aggregator Service.
• Secret: The Secret key (token) generated inside Polarion. ( Administration Repositories
Configuration)
Tip
Keep your secrets safe. Store them in a secure location.
2. Put the updated post-commit into the /hook folder in the SVN repository.
3. Make it executable by entering the following terminal command
chmod a+x $REPOSITORY_HOME/hooks/post-commit
It will run after a commit and a revision is sent to the External Repository Aggregator Service.
Resource Traceability gives Polarion users the power to link source code assets semantically. (Link Work
Items directly to the source code function, method or variable that implements them.)
This gives managers and auditors a traceable record of all implemented changes and developers a link to
who and what prompted a task, in case further clarification is required.
Developers simply add a custom comment to the source code they’re developing and it is automatically
parsed to any Work Item (Requirement, Change Request, Improvement, Bug Fix etc.) that the code
implements.
Administrators can configure how and when this information is parsed in multiple configurations, using
multiple parsers, to satisfy all of their technical and time constraints.
Note
SVN, GIT, or Polarion's default repository are supported. If you want to enable Resource
Traceability for other Git-based services, you must create a local Git repository clone.
Configure Where, When and How Resource Traceability parses data to Work Items.
Check logs for errors.
For Administrators: Check the new log4j-rt log regularly for parsing results and errors.
Learn the source code syntax.
For Developers: The source code syntax used to link where they implemented a source code
change to the Work Item that requested it.
Warning
• If planning to use Resource Traceability with large or multiple repositories, increase Polarion’s memory
allocation.
• Polarion does not auto pull to the clone, and so the clone can become stale. Polarion does not report
any of the changes made to the primary Git Repository.
Configure the git clone cron job as described in the Configure the server side cron job for git clone
topic.
Related Topics
Link a resource
To enable Resource Traceability using GitLab, you must create a local Git clone. However, there are
additional steps you must take to auto pull to the clone, otherwise Polarion does not report any of the
changes made to the primary GitLab Repository.
After you created the local Git clone from the source GitLab Repository, configure the external repository
and Resource Traceability in Polarion.
To automate the git pull from the Master Repository, you can configure a cron job on the machine where
the Git repo was cloned by using a shell script to sync the clone. This cannot be done from within Polarion:
Procedure
1. Open your terminal or command prompt and navigate to the directory where your Git clone is
located.
2. Create a shell script that contains the commands to sync your Git clone. For example, create a file
named sync.sh and open it in a text editor.
3. Add the following commands to the sync.sh file:
#!/bin/bash
chmod +x sync.sh
6. Open the crontab file for editing by running the following command in your terminal:
crontab -e
7. If this is your first time using cron, you may be prompted to choose an editor. Select your preferred
editor, such as Nano or Vim.
8. Inside the crontab file, add a new line to specify the schedule for your cron job. For example, to run
the sync every day at 3:00 AM, you can add the following line:
Replace /path/to/your/sync.sh with the actual path to your sync.sh file, and /path/to/your/sync.log
with the desired path to the log file where you want to capture the output and errors (for
example /var/log/sync.log).
9. Save and close the crontab file.
The cron job is now set up to automatically sync your Git clone with your GitLab Master Repository
based on the specified schedule. Any output or error from the cron job is logged in the specified log
file. Make sure the script file, paths, and cron schedule are adjusted according to your specific setup.
For a Resource Traceability server embedded inside Polarion - The default configuration:
The Resource Traceability server is set to start by default. Administrators that do not wish to use the
Resource Traceability feature can disable it by adding the following property to the polarion.properties
file.
com.siemens.polarion.rt.startRtServer=false
Customize the following properties to use a different PostgreSQL instance for storing links:
com.siemens.polarion.rt.db.jdbcUrl
com.siemens.polarion.rt.db.username
com.siemens.polarion.rt.db.password
Warning
To ensure that a cluster setup installs correctly, the property below was added to the shared
polarion.properties file. This property should be removed before setting up a Resource Traceability
server.
com.siemens.polarion.rt.startRtServer=false
(If the RT node goes down, it can be quickly restarted without having to restart the Polarion application
itself.)
Adjust database:
Procedure
To create a database on a new location on a shared storage, please contact Polarion support.
Note
To connect a Resource Traceability Server to an external database, the following should be used:
com.siemens.polarion.rt.db.jdbcUrl=jdbc:postgresql:
//<databaseLocation>:5433/polarion
com.siemens.polarion.rt.db.username=<username> (e.g polarion)
com.siemens.polarion.rt.db.password=<password>
Procedure
1. Mount the shared storage to the Resource Traceability node. (Required to share the
polarion.properties file.)
2. Make a copy of your polarion.properties file for Resource Traceability.
3. After making the copy, replace the content with the content below and adjust the properties if
needed:
com.siemens.polarion.rt.polarionUrl=http://polarion-cluster
com.polarion.application=polarion.rt
#Shared folder between the machines that make up the cluster
#default Linux: com.polarion.shared=/opt/polarion/shared
#default Windows: com.polarion.shared=\\\\<shared_services_host>\\Polarion
com.polarion.shared=/opt/polarion/shared
TomcatService.ajp13-port=8889
base.url=http://rt-hostname
#Control port and host name for shutdown requests
controlPort=8887
controlHostname=rt-hostname
com.polarion.platform.internalPG=polarion:polarion@localhost:5433
Procedure
1. Adjust the Virtual Memory properties so that they fall into the -Xms500m -Xmx2g range.
(These values will vary depending on the number of external repositories, their size and scheduling.)
• For Windows: in the [POLARION_HOME]/polarion.ini
• For Linux: in [POLARION_HOME]/etc/config.sh
2. Restart Polarion
Adjust the Polarion server to work with the standalone Resource Traceability server.
When connecting a Polarion cluster to a Standalone Resource Traceability Server, add the following
properties to each node:
com.siemens.polarion.rt.startRtServer=false
com.siemens.polarion.rt.url=http://rt-hostname
Note
com.siemens.polarion.rt.url should point to the base.url of the standalone Resource
Traceability server.
Https setup is done like any other Polarion instance. Certificates must also be imported into the truststores
of both the Polarion and Resource Traceability servers.
To ensure a high-availability setup, use the Standalone Resource Traceability Server setup above.
com.siemens.polarion.rt.startRtServer=false
To correctly configure a Resource Traceability cluster, setup Reader and Writer nodes.
• Reader Node: Can only return links that are stored in the Resource Traceability database for a specified
Work Item.
(There is no limit to the number of Reader nodes located in the cluster.)
• Writer Node: enables configuration updates, collects information from the repositories and stores data,
(files, configurations and links), in the database.
(Only a single Writer node is allowed in the cluster.)
Note
Writer node settings can be left as is, because a Polarion instance starts the Resource Traceability (RT)
server by default as a Writer instance.
Customize the following Properties to use a different PostgreSQL instance for storing links:
(A database on a different node acts like a separate PostgreSQL instance and the properties below should
also be provided on the node or instance pointing to the database.)
com.siemens.polarion.rt.db.jdbcUrl
com.siemens.polarion.rt.db.username
com.siemens.polarion.rt.db.password
All Reader nodes should be configured to send different "write"-requests to the Writer node.
They should also all be marked as Reader nodes by setting the following property to 'false'.
com.siemens.polarion.rt.dataCollectingEnabled=false
The following property should be linked to the Writer node's base URL.
com.siemens.polarion.rt.writerNodeUrl=
Define the same database properties in the following properties for every Reader node.
They should be linked to the Database that is used by the Writer node.
This enables the Polarion located on a Reader node to send a request to fetch Work Item links for its local
RT Server instance along will all other requests to the Writer node — configuration changes, for example.
com.siemens.polarion.rt.db.jdbcUrl
com.siemens.polarion.rt.db.username
com.siemens.polarion.rt.db.password
Configure repositories
• Currently only a single branch per GIT <repositoryConfiguration> is supported. The local
repository must be switched to the branch defined in the configuration.
• To collect resources from different branches in GIT, create a clone of the repository in the desired
branch and set it up as another repository in External Repository Configuration and the resource-
traceability.xml file.
• To use an External Repository (a repository other than the internal/default SVN repository), configure
the repository before configuring the resource-traceability.xml file.
Note
SVN, GIT, or Polarion's default repository are supported. If you want to enable Resource Traceability
for other Git-based services, you must create a local Git repository clone. For more information, see
the Resource Traceability configuration checklist.
(To parse the source files for Resource Traceability annotations.)
Changes to a Repository
When considering change to an existing repository, it is essential to understand the potential impact on
resource traceability.
• If the root URL of the external repository is changed, no recollecting of resources is processed: no old
records are removed, and no new ones are processed.
• If the ID of the external repository is changed, then old records are removed and new ones are
processed.
For example, if a user changes the URL of the repository without changing the actual repository —.
replaces http:// with https://, for example, or the changed URL points to the same repository
with same structure as old one, then there is no problem with not recollecting anything. However,
if a user changes the URL of the repository and the new repository has different structure, then
the administrator should change the ID of the current repository configuration and also change it in
resource-traceability.xml in order for everything to be recollected.
Procedure
1. Log on with administrator permissions for the project you want to configure and open the target
project.
Use the sample XML file above as a structure guide and customize it using the tags below:
Warning
If a configuration is deleted, all the links associated with it will also be removed.
Note
See the <scheduler cron="0 0/60 * * * *" /> tag below for details on how to stop a
parser from running a <RepositoryConfiguration> without deleting existing links.
<categories>
The wrapper tag used for the <category id="first_category" name="Codebase"> tag.
For Resource Traceability, a category lets administrators organize one or more
<RepositoryConfiguration> tags by similar criteria — Codebase, Marketing Material, etc.
The configuration file must contain one <categories> tag with one or multiple <category> tags
defined for each project.
The resource-tracability.xml file must contain at least one category but multiple
<categories> can be defined for each project.
The <category> tag lets administrators create multiple configurations, based on different criteria,
within the singleresource-traceability.xml file.
If parser and/or scheduler are set on the category level then it will apply to all repositories
inside that category, unless explicitly set on the <RepositoryConfiguration> level.
Multiple <repositories> can be configured on this level by creating a
<RepositoryConfiguration> for each.
Define a unique system ID and common name.
Use this tag to define multiple configurations for a single repository by entering a unique name for
each configuration in id= and use the ID of the repository defined on the Repositories Administration
page ( Administration Repositories) as the repository=value.
<branches>
The wrapper tag used for the <branch id="Version 0.9" path="Demo Projects/
elibrary/branches/0.9"/> tag.
<path dir="elibrary/trunk/src/main/java"/>
Note
One or more <paths> can be defined per Repository.
If branches are used, specify, if needed, the specific path location(s) inside the branches that should
be processed by the parser.
If not specified the whole branch directory will be processed.
If branches are not used, set the absolute location of the path starting from the root of the repository,
including the "Project" and/or "Project Group".
<fileParser>
The wrapper tag used for the <fileParser id="javaParser"
name="com.siemens.polarion.rt.parsers.java" extensions=".java"> tag.
<fileParser id="javaParser"
name="com.siemens.polarion.rt.parsers.java"extensions=".java">
The parser (Java, C etc.) used to extract the traced content and populate the links that appear in the
Linked Resources section of a configured Work Item.
One or more <fileParser> can be defined per <RepositoryConfiguration> or <category>
tag..
Define a unique parser system id, the parser's name, and the file Extension it should search for.
Available Parsers:
For Java - <fileParser id="javaParser"
name="com.siemens.polarion.rt.parsers.java" extensions=".java">
For C - <fileParser id="cParser" name="com.siemens.polarion.rt.parsers.c"
extensions=".c">
For XML - <fileParser id="xmlParser"
name="com.siemens.polarion.rt.parsers.xml" extensions=".xml">
<schedulers>
The wrapper tag for the <scheduler cron="0 */60 * * * *"/> tag.
One or more <schedulers> can be defined per <category> or <RepositoryConfiguration>
tag.
Tip
To keep existing links but stop the further processing of new links, remove the
<scheduler cron="0 */60 * * * *"/> tag from the target <category> or
<repositoryConfiguration>.
Note
Use Cron syntax to define the parsing schedule. See the examples of cron Expressions section for
details.
(See Cron Trigger Tutorial to view an online tutorial.)
If the Java or C parsers encounter something that they cannot process — incorrect comment syntax, for
example — they will skip the offending code, log an error and continue parsing the rest of the file.
If the XML parser encounters something that it cannot process, then it will stop processing the rest of the
file, and log an error.
The XML parser automatically detects encoding tags (for example, <?xml version="1.0"
encoding="ISO-8859-1"?> but if no heading exists it will use UTF-8.
(If it does and the encoding is not UTF-8 a parsing error will occur.)
Procedure
1. To add the Resource Traceability Linked Resources section to selected Work Items.
3. Select a Work Item type to add the Resource Traceability feature to and click Edit .
4. Insert the following line where the new Linked Resources section should appear in the Work
Item.
<extension id="linkedResources" label="Linked Resources"/>
(label="Linked Resources" is the section title that appears in the Work Items.)
Make sure that the right users have permission to view Linked Resources in a Work Item.
Permission to read can be assigned to individual user names By Permission, By Role or through Custom
Sets.
By Permission
Procedure
4. Expand the Work Items section and then the Fields section within it.
6. Make sure that the applicable users have a Check mark in the box in the Granted column beside
their user name(s).
7. Click Save .
By Role
Procedure
4. Select a Role from the Role drop-down list, expand the Work Items section and then the Fields
section within it.
5. Make sure that there's a check mark beside Permission to READ field “Linked Resources” .
6. Click Save .
Note
Permissions can also be granted via Work Item Custom Sets.
Link a resource
Developers add a source code comment using the syntax below to customize what information is included
with the linked resource.
You can link multiple Work Items with the following syntax:
/**
* {@wi.LinkRoleAsASingleWord Project WorkItemID} {@wi.LinkRoleAsASingleWord
Project NextWorkItemID}
*/
Example
/** {@wi.tests EL-115} {@wi.tests EL-122}*/
If administrators
set the View
Traceable
Resource Local
URL. (
Administration
Repository )
To add a linked resource like the example above (for Java or C parsers), add the following commented code
where the change was implemented.
/**
* @wi.implements elibrary/EL-115:164 Returns author of this book
*/
public String getAuthor() {
return this.author;
}
Multiline message
Just start the message with a "{" and end it with "}".
/**
* {@wi.implements elibrary_alm/EL-122 messages can take up
* several lines in the code. Just surround the whole parsing syntax
* with {}
* Anything commented after will not be included.
*/
Supported elements
Developers can add the Resource Traceability feature to comments for the following elements:
• method
• constructor
• field
• class
• interface
• enum
• static block
For C: (Supported extensions - .c, .h and additional custom extensions depending on how the parser and
project preferences are configured.)
• function
• function prototype
• global variable
• struct
• union
• enum
Where the comment should be placed, varies depending on the parser used.
If using a Java or C parser, the Resource Traceability syntax links the element that directly follows it in the
source code.
For XML:
For XML, add the comment inside the target element as in the example below.
The second example will link to the Plugin instead of the groupId.
Users can use the visual query builder to search for Work Items with or without Linked Resources.
Configure Connectors
While Polarion provides solutions that encompass all aspects of the application life cycle, it may not always
be possible or realistic for organizations to adopt Polarion solutions for the full spectrum. For example,
your team or department might want to use Polarion for requirements management, but other teams or
departments are currently unable or unwilling to adopt the Polarion solution applicable to their function.
For example, development teams might want to keep their present tool for task and issue tracking, or
testing teams might want to keep on with their current test management and testing tools.
If we identify sufficiently widespread demand for interoperability with Siemens or third-party solutions
in order to help prospective customers remove barriers to adoption of a Polarion solution within their
organizations, we may develop Connectors for these third-party solutions. Connectors are integrated
directly into the Polarion platform rather than implemented as extensions. Connectivity and data exchange
is configurable directly in Polarion's Administration interface, in the Connectors topic, and
technical support is provided according to the customer's subscription plan.
• Atlassian Jira
• Opentext ALM / Quality Center (Version 15.0.1)
• IBM DOORS
• MATLAB Simulink
• Microsoft TFS
• Sparx Enterprise Architect
• Teamcenter (Direct Integration / Linked Data (OSLC) integration)
• Teamcenter Share
More Connectors are available as extensions. You can download them from the Polarion Extensions
portal. You must install them per bundled instructions, after which they can be configured in
Administration. Some of these extension Connectors are developed and supported by Polarion, while
others are developed and supported by partners. The status is indicated on the respective pages of the
Extensions site.
Overview of functionality
Connectors provided either unidirectional or bidirectional synchronization of data between Polarion and a
third-party system. The synchronization process generally works in the following way:
1. Load all items that match a query and other parameters from Polarion.
2. Load all items that match query and other parameters from other system.
3. Determine what needs to be done with the items:
• Create pairs of items that have been synchronized before by looking up the connection information
stored in folder [POLARION]/data/synchronizer.
• If the partner item is found in the queried items, create a pair to be synchronized.
• If an item is connected, but the partner item was not found, try to load the partner item by ID to
create a pair to be synchronized.
• If loading the item by ID fails, consider the item as deleted.
• Consider all items that are not connected according to information in [POLARION]/data/
synchronizer as new items.
4. Create new items, synchronize paired items, and propagate deletions according to the Connector
configuration.
In summary, if an item matches the query on either side (Polarion or third-party system), it will be
synchronized.
Other Help topics explain how to configure a connection to third-party systems, define synchronization
pairs, map data interchange between Polarion, and another system, and use features of the Connectors.
Related Topics
Jira overview
OpenText ALM / Quality Center
Linked Data applications overview
Configure synchronization overview
Configure Connectors overview
Microsoft TFS (Azure DevOps)
Related Topics
DOORS overview
Use the Connector for DOORS to import a complete IBM DOORS project into Polarion. The connector works
with all DOORS 9.x versions running on Windows. It will still work if Polarion is running on Linux.
Once imported, the Connector can be used to continuously import changes done in the DOORS modules.
Tip
To ensure that the synchronization runs smoothly, make sure that there is a stable and robust network
connection between DOORS and Polarion.
• DOORS only uses a single CPU core per thread so you should only run a single Connector session to a
single Polarion Project at any given time , and merge the data once it's complete.
• Image objects are not supported, but images inserted as OLE objects are.
• If a DOORS module’s structure can't be mapped to a document flow, Requirements may not appear at
the expected location. For example, in DOORS you can create a structure like this example:
Heading
Requirement
But a document flow would recognize it as;
Heading
>Requirement
The connector would therefore preserve the parent child relation by re-positioning the requirement to:
Requirement
Heading
Headings that are hierarchically below a Requirement can’t be inserted into the document during
import.
Example:
Requirement
>Heading
• Module properties are not imported; object properties are imported.
• DXL attributes will be imported into Polarion as static data , so they will not act as they do in DOORS.
• The thumbnails generated for imported OLE objects are not always accurate, especially when the
conversion takes place on Linux.
• The synchronization of superscript- and subscript-formatted text between IBM DOORS and Polarion is
not supported.
Note
ImageMagick must be installed and configured to see the thumbnails of imported OLE Objects.
Synchronizing large DOORS modules that contain a lot of OLE objects consumes a lot of memory. If you're
planning to import them, assign at least 4 GB to Polarion.
If you see an error like Expected 5 objects (top-level) from Doors but received 4 in the
synchronizer log, it's probably because Polarion has run out of memory, and you'll need to assign more.
You can confirm this by looking for java.lang.OutOfMemoryException entries in the main Polarion
log.
Note
The Polarion REST API used by Doors to exchange data is secured with a Personal Access Token.
Procedure
Import procedure
Procedure
1. Log on to Polarion with administrator permissions for the project where you want to import from
DOORS, and open the project.
Tip
Access Polarion from the same computer that hosts your DOORS client.
Click the check box again so that they turn green to re-configure them.
Remove the check mark on any modules you do not wish to re-import.
Warning
The maximum number of modules that can be configured in a single import is fifty (50). However,
there is no limit to the number of preconfigured (black check marked) modules that can be
imported. If more than fifty modules need to be configured, you must run the connector multiple
times.
9. Configure the Work Item type to be used when importing and configure how the DOORS attributes
are mapped to Polarion attributes.
10. The Create missing attributes and values check box will automatically create all missing custom
fields and enumeration values.
This topic and subtopics cover how to configure external Linked Data applications to work with Polarion.
Polarion's external Linked Data support lets users link to objects from other tools, such as Teamcenter. The
Linked Data feature can be used in the following ways.
• Act as a Linked Data consumer, by creating links for Work Items or LiveDocs from objects that reside on
external Linked Data enabled tools.
Linked Data consumers can connect to Polarion using the root service URL http://polarion-
server/polarion/oslc/rootservices
Polarion provides the OSLC RM and CM domain that enables Linked Data consumers to link to Polarion.
Delegated user interfaces are provided.
• Act as an Linked Data provider. Link Polarion Work Items to objects that reside on external Linked Data
enabled tools.
This is normally done by creating or selecting a remote object in a delegated user interface provided by the
external Linked Data application.
Administrators can define linking rules in the Linked Data Semantics and Linked Data Mapping
configuration pages of Polarion Administration.
1. In Polarion, a user selects a Requirement type Work Item that is considered a rm:Requirement
according to the Linked Data Mapping configuration.
2. The user selects the is implemented by link role as the backlink for the implements link role.
3. The implements link role is mapped to cm:implementsRequirement based on the Linked Data
Mapping configuration.
4. The reverse for that is rm:implementedBy based on the Linked Data Semantics configuration.
5. The Linked Data link type rm:implementedBy can be used from rm:Requirement to
cm:ChageRequest according to the Linked Data Semantics configuration.
(So only dialog boxes that can be used to select cm:ChangeRequest remote objects are shown.)
6. After the user selects a cm:ChangeRequest the available link roles are also filtered so that only
those valid for use with rm:Requirement and cm:ChageRequest are displayed.
After one or more Linked Data Friend servers are defined, connecting Polarion with external application
servers, and the relevant Linked Data Associations are configured, an icon appears in the Linked
Work Items section of Polarion Work Items. Users can then Link Items to and from external Linked Data
applications.
Tip
• Please make sure to apply the Linked Data configuration prerequisites.
• If changes occur on a remote service provider (like domains added or removed), that provider must be
re-added to the Polarion linked data applications configuration.
• When using the OSLC HTTP endpoints (like CreationFactory or the OSLC Query Capability), the
preferred method of authentication is using personal Access Tokens.
• If Polarion, the remote system, or both are configured to use Single Sign-On (SSO), refer to section
Configure Linked Data with SSO.
Polarion's OSLC REST API endpoints and OSLC creation factories can be discovered starting at the root
service URL: http://[Polarion-server]/polarion/oslc/rootservices.
The following table shows which OSLC endpoints are supported for a Polarion field of a given Polarion data
type for Resources (Work Items). YES means it is supported, NO means it is not supported.
Example: 2023-09-12
Caution
Since OSLC does not support simple date values,
this format might change in future releases.
Examples:
2023-09-12T10:33:38+02:00
2024-02-29T00:00:00Z
2025-07-22T09:30:00
Time YES YES NO Format: HH:mm:ss.SSS+/-hh:mm
Example: 12:34:56.789+01:00
Caution
Since OSLC does not support simple time values,
this format might change in future releases.
LinkedWorkitem YES NO NO
s
ExternallyLink YES NO NO
edWorkItems
LinkedOslcReso YES NO YES
urces
The following table shows which OSLC endpoints are supported for a Polarion field of a given Polarion data
type for Resource Collections (LiveDocs). YES means it is supported, NO means it is not supported.
Limitations
Prerequisites
Please apply the following settings to ensure that Polarion's Linked Data capabilities work securely.
Caution
We discourage the use of self-signed certificates. (Especially in cloud environments.)
Example
◊ /etc/httpd/conf/httpd.conf
◊ /etc/apache2/apache2.conf
<IfModule mod_headers.c>
<If "%{REQUEST_URI} =~ m#^/polarion/oslc/services/oauth#">
Header edit Set-Cookie ^(.*)$ $1;Secure;SameSite=None;
</If>
</IfModule>
Note
You may need to specify multiple ports, depending on the configuration of the provider server.
If you want to link to another Polarion instance, please do not use an URL with a path.
For example, use https://polarion.example.org instead of https://
polarion.example.org/polarion
Related Topics
A Friend server is one that hosts an application that Polarion exchanges Linked Data with. A common
scenario is data exchange between Polarion and Teamcenter. Configuring Polarion to recognize the
external server is the first step in setting up to use Linked Data.
Tip
• Please make sure to apply the Linked Data configuration prerequisites.
• This is a global-scope configuration, and you need administrator permissions for Global
Administration.
• If changes occur on a remote service provider (like domains added or removed), that provider must be
re-added to the Polarion linked data applications configuration.
Procedure
2. If you are not already in Administration after the previous step, then in the Tool view of
Navigation, click Administration.
If you now working in a project, then in Navigation click Global Administration.
Tip
If you are already in the global administration scope, Navigation displays the Return to Portal link.
Tip
If you have not already configured Linked Data Semantics, you should do that first.
After Polarion and an external Linked Data application are configured to communicate with each other, an
Association between the two must be created in relevant projects before being able to link items back and
forth.
Tip
• Please make sure to apply the Linked Data configuration prerequisites.
• Make sure to have enabled the External Linking option in global Administration:
Administration Work Items Linking.
• You might need to review the configurations for Linked Data Mapping and Linked Data Semantics
before proceeding.
Caution
If Linked Data domains are added or removed from the Friend server, you must re-add the Association.
Procedure
Depending on the selection, one or more check box options appear in the Artifact Container field.
Note
If connecting to SIEMENS' Teamcenter for the first time in a session, an additional dialog box opens
requesting log on to Active Workspace.
Enter your Teamcenter credentials.
5. In the Artifact Container field, select the option(s) you want for this Association.
6. Click Add to create the new Association.
Items can now be linked between Polarion and the External Linked Data application.
What to do next
If you create an Association in Teamcenter, the following options appear in the Artifact Container field:
Change Management Link to Teamcenter items specific to Change Management. PR, ECR, or
ECN, for example.
Core Services Create generic links to any Teamcenter item type.
Embedded Software Link a release in Polarion to Teamcenter.
Management
Requirements Management Link to Teamcenter requirements.
Linked Data Mapping is used to map custom Work Item and link types to semantic types defined in
Linked Data Semantics.
Linked Data Mapping can be defined in both global and project scope. Project-scope Linked Data Mapping
overrides the global-scope mapping in one specific project.
1. Log on with administrator permissions for the scope you want to configure.
2. If you want to configure a project, open it. Invoke the Open Project or Project Group dialog box if
necessary to locate the project.
Related Topics
Linked Data Semantics are defined in the global scope (Global Administration), and are described on the
Linked Data Semantics Administration page:
Warning
When adjusting the Linked Data Semantics configuration it is essential to make sure that the external
Linked Data application understands the adjusted semantics.
Adding a custom resource or link type will not work if the external application does not understand the
configured custom types.
(Polarion's default configuration only maps the default Work Item Types.)
See the configuration page to categorize custom Work Item types as a Change Request or Requirement.
Related Topics
These remote attributes belong to the items that are linked to the Polarion item.
To show linked item attributes in Polarion without opening the Linked Data delegated UI:
Procedure
1. Log on to Polarion with administrator permissions, select the scope (global or project level) and enter
Administration.
( Administration.)
2. Enter the Linked Data Appearance section to configure the remote attribute(s) that you want to
show for your target remote item type(s).
Note
There is currently no "translation" of any of the remote attribute values.
Examples
Procedure
1. <remote-attributes-configuration polarionTypes="task"
remoteOslcType="oslc_cm:ChangeRequest"> <attribute label="Status"
oslc="oslc_cm:status"/> <attribute label="Owning
User" oslc="dcterms:creator" visible="false"/> </remote-attributes-
configuration>
The Linked Change Requests section does not display the Owning User column because its visible
flag is set to false. (It shows the Status column instead.)
Procedure
1. <remote-attributes-configuration polarionTypes="changerequest,defect"
remoteOslcType="oslc_cm:ChangeRequest"> <attribute label="Status"
oslc="oslc_cm:status"/> <attribute label="Change Owner"
oslc="dcterms:creator"/> </remote-attributes-configuration> <remote-
attributes-configuration polarionTypes="changerequest,defect"
remoteOslcType="oslc_rm:Requirement"> <attribute label="Owning
User" oslc="dcterms:creator" visible=”false”/> </remote-attributes-
configuration>
2. The following is added to the Change Request and Defect Work Item Form (Editor) Extension.
<extension id="OSLCExtension" label="Linked Requirements"
oslcType="oslc_rm:Requirement"/> <extension id="OSLCExtension" label="CRs"
oslcType="oslc_cm:ChangeRequest"/>
Result:
Linked Data Appearance configuration for the Release Work Item type:
Procedure
1. <remote-attributes-configuration polarionTypes="release"
remoteOslcType="siemens_esm:SoftwareRelease"> <attribute label="Size on
ROM" oslc="siemens_esm:memorySizeOnROM"/> <attribute label="Software
Version" oslc="siemens_esm:softwareVersion"/> </remote-attributes-
configuration>
2. The following is added to the Release Work Item Form (Editor) Extension.
<extension id="OSLCExtension" label="Linked Software
Architectures" oslcType="siemens_esm:SoftwareArchitecture"/> <extension
id="OSLCExtension" label="Linked Software Releases"
oslcType="siemens_esm:SoftwareRelease"/>
Result:
The Linked Software Releases section displays the Size on ROM and Software version columns.
The Linked Software Architectures section displays the default columns.
Linked Data works seamlessly if Polarion, the remote system, or both are configured to use Single Sign-On
(SSO). However, additional settings might be required in the Identity Provider (IdP) of these remote
systems for security reasons, because the IdPs might block their login pages from displaying in iFrames.
Below you can find examples for the configuration of Keycloak and Okta. If the remote system uses another
IdP, please refer to its documentation.
Procedure
Procedure
Note
Customizations Other Enable iFrame Embedding must be disabled.
Troubleshooting
If the remote system and Polarion use different Identity Providers, there can be rare cases where your
browser loses the login session to Polarion. In that case, it is possible that Polarion's login dialog does not
work as expected if it is shown in an iFrame. This is the case for example when creating an OSLC link or
when viewing the preview of a linked item. To resolve this, open a new tab and log in to Polarion so that
the browser gets a new session.
Investigating problems related to Linked Data with SSO is a challenging task, as many different systems
and technologies come into play. On one hand, there are different servers with firewalls and (reverse)
proxies. On the other hand, there are enterprise antivirus software and browsers with different security
Configure synchronization
Some Polarion users need to connect with one or more supported third-party systems, such as Atlassian
Jira, OpenText ALM / Quality Center, or IBM DOORS via a Polarion Connector. Such connections,
and the data synchronization they enable, help to maintain traceability and process workflow across
system boundaries. Users of third-party systems leverage their current tool investments while gaining the
advanced lifecycle management and traceability provided by Polarion.
Here is a brief overview of the process of configuring a Connector for synchronization across systems.
Procedure
1. Configure a Connection.
Tip
If you need multiple projects to access the same third-party system, configure a Global
Connection.
Before you begin using any Connectors, be sure to have your system backup administrator include the
Connectors data folder of your Polarion installation in routine backups. Losing Connector data will result in
items being recreated rather then updated when systems are synchronized.
For details, please refer to Backup Polarion data, especially the Connectors Data section.
Tip
1. Be sure to read through all the topics about Connectors and synchronization before configuring and
creating a synchronization pair, so that you become familiar with all the capabilities.
2. Spend some time planning out your data synchronization between Polarion and the third-party
systems. As already stated, ensure you have a backup process in place, in the event you need to
return to a previous state.
Configure Connections
A Connection refers to data connection to a specific third-party server containing data that you want to
replicate and synchronize with Polarion. Objects from the third-party system are identified based on their
ID and the Connection that was used to synchronize them.
Warning
• If you specify multiple Connections for the same third-party system, you will duplicate items. To
prevent this, configure a Global Connection.
• Only a single synchronization can run with a specific Connection at any given time.
Tip
Read through special considerations for Jira before connecting to a Jira server or the system specific
instructions for DOORS, Opentext ALM / Quality Center, MATLAB or Microsoft TFS.
This configuration is possible in both the global and the project scope. You must have administrator
permissions for the scope you want to configure. Settings are basically the same in both, but the access
procedure differs slightly, as will be described.
Procedure
1. Log on with administrator permissions for the project you want to define the new Connection for.
(The Required fields will vary depending on the third-party system you are connecting to.)
Note
Possible license request:
Some Connectors require that a valid license for the Connector is present on the Polarion system.
The dialog box displays a message if the license is not present, and you cannot complete the
configuration until a license is obtained and installed.
Because items are identified by their ID and the Connection that creates them, links between different
projects need to use the same Connection. Therefore, use a Connection configured in the global scope
to synchronize linked items to different Polarion projects. This ensures that the links between the items are
recreated in Polarion. For example, to import links from defects in Project B to requirements in Project A,
defining the mapping of the link parameter for the defect type is sufficient.
If the items are not in one sync pair, it may be necessary to execute the synchronization twice, because
links cannot be created when there is no target for them yet. The items must be created during the first
sync, and then on next sync they will be linked.
If you specify multiple Connections for the same third-party system, you will duplicate items. If want
multiple projects to access the same third-party system, you must configure a global connection for sync
pairs.
The logon credentials for global connections are not stored in the User Account Vault. Users can enable
Connections defined in the global scope in any project by supplying logon credentials.
Procedure
(Click Open Project or Project Group if Repository does not appear in your Recent list.)
(The Required fields will vary depending on the third-party system you are connecting to.)
Tip
Some Connectors require that a valid license for the Connector is present on the Polarion system.
The dialog box displays a message if the license is not present, and you cannot complete the
configuration until a license is obtained and installed.
Procedure
3. Click Edit beside the global connection you configured in the Connections list.
4. Enter the third-party user Password.
Caution
If you don't enter the Password again on the project level, the connection will not appear in the
Connect to drop-down menu in step 6.
7. Click Create.
8. Your now ready to configure Polarion and the third-party sync pairs.
A Synchronization Pair (sometimes called a sync pair in the user interface) defines how a specific type of
information is exchanged and synchronized between Polarion and the target third-party system configured
in a Connection.
The Sync Pair Configuration lets you configure settings for Polarion and the third-party server
connections, data propagation, and data mapping.
Warning
• Before attempting this configuration, make sure that you have created a Connection to the relevant
third-party system
• Need multiple projects to access the same third-party connection?
Create a global connection, then project-level sync pairs for each project.
Procedure
1. Log on with administrator permissions for the project where you want to define a new
Synchronization Pair.
2. Open the relevant project.
7. Specify a unique identifier for the new Synchronization Pair in Sync Pair ID. This ID can be specified in
Jobs that run this Synchronization Pair. Example: Jira Sync 1
8. Select a Connection in the Connect to field. The list in this field is populated with the names of all
existing Connections.
9. Click Create to create the Synchronization Pair configuration.
The Sync Pair Configuration page for the new Synchronization Pair loads and displays settings and
data mappings.
Account Required. The authentication key from the User Account Vault that contains a user name
vault key and password that the Connector can use to access the Polarion server.
You may want to configure a new key specifically for use with Connectors, or even
different keys for different Connectors if you connect Polarion to more than one third-
party system. For details about Account Vault keys see:Configure the User Accounts
Vault.
Warning
Once an item has been synchronized, it will continue to be synchronized until it does
not match the query configured for Polarion and the query configured from the third-
party system.
Live Optional. Specified as space name/Document name. If specified, only Work Items
Document from the specified LiveDoc Document in the specified space will be synchronized. The
Document's Work Items are filtered according to the filter specified in the Query field, if
any.
Note
Make sure that your Polarion license includes the creation and modification of Live
Documents.
Use title as Optional. Select this option if the title of the Document specified in the Live Document
root field should be treated as the root element in the synchronization. When selected, the title
itself will not be synchronized, but all synced items will have it as an ancestor.
When you've set the desired properties, test the settings using the Test Connection button. A green check
mark appears if the configuration is valid as specified. A descriptive error message appears if a setting
is incorrectly configured. This connection, and the one to the third-party system described below must
succeed before you can proceed to complete the Synchronization Pair configuration.
To the right of the Polarion Configuration section there is another section with connection settings for
the target third-party system. The fields vary depending on the system, but should be similar enough
to Polarion's settings to recognize. (It is expected that you are familiar with the third-party system
and understand the fields). Label semantics are taken from the third-party system. After you specify
these settings, test the connection with the section's Test Connection button. This connection, and
the one to the Polarion server described above, must succeed before you can proceed to complete the
Synchronization Pair configuration.
The General Settings section lets you control the propagation of new items and deleted items between
Polarion and the third-party system.
Propagate This setting works much like Disabled except that it controls how deleted items are
deletes synchronized.
Once both connections are tested and working, the next step is to map type and field values.
Tip
When you map attachments uni-directionally, you can choose to not propagate deletes. In this case,
attachments added to Work Items on the target side of the synchronization will not be deleted, because
they do not exist on the originating side.
• Type mapping: Maps one or more artifact types defined in your Polarion project to their equivalent
artifact type in the third-party system's project.
• Field mapping: Maps one or more Work Item fields of your Polarion project to their equivalents on the
third-party system, and specifies the direction and precedence of synchronization.
First, map the Polarion Work Item type(s) you want to synchronize to their equivalents on the third-party
system. Create a row in the Type Mapping section for every Work Item type you want to synchronize.
Procedure
1. In the Actions column of the Type Mapping section, click Create New.
2. In Left Type, select a Polarion Work Item type in the list. This type will be synchronized with a
third-party type specified in the Right Type column.
3. In Right Type, select a third-party artifact type in the list. Select third-party system's equivalent of the
Polarion type specified in the Left Type column, so that the fields and attributes of these two types
can be synchronized.
Results
Repeat the foregoing steps if there are more types that need to be synchronized.
Tip
Make sure that you map all types that might be synchronized in accordance with the queries defined in
the Polarion and third-party configurations. If you only want to sync specific types, you must configure
the queries to filter your target types. For Polarion set the Query field in the Polarion Configuration
section and have it filter for all types defined in the Type Mapping section. For example, if only Task
items are to be synchronized, specify a query that returns only the Task Work Item type.
After mapping the Work Item types, you can configure how fields of Polarion Work Items are mapped to
fields or attributes of the equivalent artifacts on the third party system. You do this in the Field Mappings
section. You can specify field mappings applicable to all types, and field mappings applicable to specific
types. The latter is especially needed if you want to synchronize one or more type-specific fields.
Field mappings also specify the synchronization direction, and in the case of bidirectional synchronization,
the precedence.
Procedure
1. Select a value in the Left Field list. The list contains Polarion Work Item fields, and the one you select
is to be matched with a field of the third party system. For example, the Title field of Polarion Work
Items might be matched with a field with the same name in the third-party system, or another field
that is the equivalent.
2. Select a value the Right Field list. The list contains names of fields or attributes of the third-party
system. The field you selected in Left Column will synchronize with the third-party system field you
select here. For example, if the third-party system is Jira, and you selected Title in the previous step,
then you would probably select Summary in this field.
3. Select a value in the Direction list. This specifies if the synchronization is bi-directional, or only from
Polarion to the third-party system (Left to Right), or only from the third-party system to Polarion
(Right to Left).
4. If you selected Bidirectional in the previous step, you should review and set Primary Direction.
This is the direction that will be take precedence if there is a conflict. For example if the Title
field is changed in Polarion, and its equivalent in the third-party system is also changed between
synchronizations, there will be a conflict when the next synchronization occurs.
Choose which direction should take precedence. For example, if you select Left to Right, the value of
the Title field in Polarion will overwrite the changed value of the equivalent field or attribute in the
third-party system during the next synchronization.
If you want to map fields that are configured only for a specific Work Item type — a custom field named
Task Category for the Task type, for example — specify the mapping in the last subsection of Field
Mappings.
Tip
• Warning
IMPORTANT: Do not try to synchronize to the Type attribute since type is already mapped via the
configured Type mapping. Overwriting the Type using a field mapping will cause unpredictable
behavior.
• The UI does not display which attributes are read-only, but you can check the sync execution log. It
displays error messages when any attempt to overwrite a read-only attribute is made.
• When synchronizing rich-text attributes like the Description field in Polarion and Jira, or Object
Text in DOORS, you should also consider synchronizing attachments. They might be referenced or
embedded within the synchronized rich-text and will otherwise be missing.
Within field mappings, you can also specify value mappings. This is required when you need to
synchronize values like users in a field like Assignee, or an enumeration value in a field like Severity.
1. Click the Edit link in any field mapping to display a dialog box in which you can set value mappings.
2. Click Add in the dialog box to add a new value mapping pair.
3. Specify the Polarion value in the Left field, and the third-party value in the Right field.
You can create multiple value mappings for any mapped field. The value that will be used in Polarion
(left side) is the ID of the enumeration option, category or user. The value that will be used for the
third-party (right side) depends on the system that you are synchronizing to.
Tip
If you are unsure about what value is used in the third-party system, start with synchronizing
the value to Polarion without mapping it. Polarion will set the value to whatever is used in the
third-party system and you can then define the value mapping based on that.
4. When you have finished all the mapping, click Save at the top of the page to save the Synchronization
Pair.
Results
You should now be able run synchronization to synchronize data between Polarion and the configured
third-party system.
Run synchronization
After you have created a Connection and added a Synchronization Pair for it, you are ready to
synchronize data between to two systems by running the Synchronization Pair. You can do this either
manually, or by setting up a scheduled Job to run the synchronization automatically at an interval of your
choosing. It may also be desirable to configure a job to run synchronizations frequently.
To explicitly invoke synchronization manually, click the Execute link for the Synchronization Pair on the
Sync Configuration page. The progress and log of the synchronization can be seen in the Monitor
topic of project Navigation. (For testing, it can be useful to open this topic in a different browser tab
before executing the synchronization.) Look for the job named Synchronization of [SYNC PAIR NAME]
(where [SYNC PAIR NAME] is the name of the Synchronization Pair executed).
You can optionally automate synchronization by creating a scheduled Job to run the Synchronization pair
at an interval of your choosing. You create jobs in the Scheduler topic of Global administration. For
more information, see Configure the Scheduler.
In the Scheduler, you need to create a new <job> element. Since Synchronization Pairs are configured in
the project scope, it is essential to specify the project ID in the scope attribute.
Example 1:
</job>
• The cronExpression attribute is optional. It's only used if you want the job to run automatically at
some defined interval.
• The <syncPair> element, replaces the [SYNC PAIR ID] of the actual ID of the Synchronization Pair
that will be executed by this job. To avoid errors, open the Synchronization Pair configuration in another
browser tab and copying the configured ID.
Example 2:
When teams work concurrently with Polarion and another tool, such as Siemens Teamcenter, Atlassian Jira,
or Microsoft Team Foundation Server (TFS), it can be desirable to run the synchronization between these
systems frequently so that the teams see changes in a timely manner. The scheduler in Polarion can be
configured to run a scheduled job that in turn runs Sync Pairs. The job can be configured to run Sync Pairs
as often as desired, within certain limits — see Caution below.
Because Sync Pairs typically have more items in scope than necessary, and synchronization time increases
with the number of items, the scope should be restricted when a Sync Pair is run frequently by a
job. You can limit the scope by using a system-specific query expression. For example, the expression
updated:$today$ limits the Sync Pair to Polarion items that have been changed on the current date. A
similar query must also be used for the remote system.
Caution
The frequency of the job running a Sync Pair must be larger than the running time of the Sync Pair when
the maximum number of items are in scope. For example, in a scenario where 500 items are changed
daily, and the running time of the Sync Pair for these 500 items is 3.5 minutes, the frequency of the
scheduled job that runs the Sync Pair should be at least 5 minutes. Otherwise, there could be a number
of jobs stacking up as newly triggered jobs wait for the previous one to finish.
com.siemens.polarion.connectors.projectLock.timeout= [Timeout in
milliseconds]
By default, new jobs will wait for other jobs in the same project to finish. When specifying this property
in polarion.properties, jobs will only wait for the configured time before they are stopped.
Synchronization Pairs can be configured globally for an entire repository. When created in the global
scope, they become Synchronization Pair Templates, that can be reused in different projects. Each
Synchronization Pair Template must use an existing Global Connection. You can create entirely new
Synchronization Pair Templates, or save any existing project-scope Synchronization Pair configuration as a
global Synchronization Pair Template.
To create an entirely new Synchronization Template, follow the same steps as outlined in Create
Synchronization Pair, but open the Repository rather then a project.
Tip
You need global administrator permissions for this configuration.
Procedure
1. Open a project in which some Synchronization Pair is configured that you want to reuse in a global
template, and enter Administration.
Results
The Synchronization Pair is saved as a template and now appears in the Synchronization Pairs table of the
Connectors page in Global Administration.
CI/CD Jenkins
• Configure connections and builds. You can either do this via the Polarion user interface, or in the
relevant XML configuration file in the Subversion repository.
• Configure Workflows to trigger builds are part of the overall process for Work Items and/or Test Runs.
• Configure import of test results, so that traceability to relevant Polarion artifacts is created and
maintained.
• Configure regular scheduling of builds.
Note
This is a project-scope configuration. You must have Administrator permissions for the project.
Follow these steps to configure a Connection to Jenkins via the Polarion user interface. You will need the
URL and authentication details for Jenkins to perform this configuration.
Procedure
Note
• Editing existing Connections in the Polarion UI is not currently supported. If you need to change a
Connection, delete it and create a new Connection with different parameters, or make the necessary
changes to the configuration in Administration Building Artifacts.
• You can pass Polarion build parameters (build stamp, author and project) to Jenkins using the
following expressions when you configure a workflow to trigger a Jenkins build:
${polarion.build.BUILD_STAMP},${polarion.build.BUILD_AUTHOR},$
{polarion.build.BUILD_PROJECT}
Tip
The Jenkins URL parameter token to invoke builds is not supported, because it is deprecated.
After you create one or more Connections to Jenkins, you can follow these steps to configure a Jenkins
Build via the Polarion user interface. You will need to know the URL of the remote Jenkins Build, and any
parameters it requires.
Procedure
5. If you want to configure parameters to pass to the Jenkins build, click Edit Parameters, and add the
desired parameters in the Build Parameters dialog box, and click OK when finished.
Tip
Click the green plus icon ( ) to add parameters to the dialog box. Click the red minus icon ( ) to
remove parameters.
Caution
Parameters polarion.parameter.* and jenkins.parameter.* in descriptor.xml, or
configured during build creation, will be overridden by workflow parameters if any exist which
have identical names.
Example: You can use the following property to define a specific timeout for a build:
polarion.parameter.buildTimeout=[Enter the number of minutes before a build times out. If
not defined the default is 1440 minutes.]
Example: You can pass the Polarion Build information to Jenkins:
jenkins.parameter.PolarionBuildStamp= ${polarion.build.BUILD_STAMP}
jenkins.parameter.PolarionBuildProject= ${polarion.build.BUILD_PROJECT}
jenkins.parameter.PolarionBuildAuthor= ${polarion.build.BUILD_AUTHOR}
6. Click Create to complete the new Build definition.
Note
Please note that editing of existing Builds in the Polarion UI is not currently supported. If you need to
change a Build, you can delete it and create a new Build with different parameters, or you can make the
necessary changes to the configuration in Administration Building Descriptors.
Tip
The Jenkins URL parameter token to invoke builds is not supported, because it is deprecated.
You can optionally configure one or more Connections for Jenkins in the configuration file .polarion/
builder/artifacts.xml. Use the Repository Browser to download the file to your local drive, and to upload it
again after editing. Edit the file with any text or XML editor application.
For each Connection you want to define, add an <artifact> element in the configuration file. Example:
<artifacts>
<artifact>
<artifactId>jenkins_production1</artifactId>
<type>jenkins</type>
<serverUrl>https://jenkins-server.toolshed.yourcompany.com/</
serverUrl>
<accountVaultKey>CI.Jenkins_integration.jenkins.jenkins_production1</
accountVaultKey>
</artifact>
</artifacts>
artifactId An identifier for the new Jenkins Connection in the Polarion system.
type In this case, since it's a connection to Jenkins, specify jenkins as the value.
serverURL The URL of the remote Jenkins server.
accountVaultKey The key of the Polarion User Account Vault entry that contains the Jenkins
credentials.
You can optionally configure one or more Jenkins Builds in the configuration file .polarion/builder/
descriptors.xml. Use the Repository Browser to download the file to your local drive, and to upload it
again after editing. Edit the file with any text or XML editor application.
For each Build you want to define, add a <descriptor> element in the configuration file. Example:
<descriptor name="qa_build">
<artifacts>
<artifact>
<artifactId>jenkins_production1</artifactId>
</artifact>
</artifacts>
<build>
<properties>
<jenkins.build.job.url>https://jenkins-
server.toolshed.yourcompany.com/job/QA%20build/</jenkins.build.job.url>
<jenkins.parameter.branch>master</jenkins.parameter.branch>
<polarion.parameter.xUnitFile>results.xml</
polarion.parameter.xUnitFile>
</properties>
</build>
</descriptor>
name An identifier for the new Jenkins Build in the Polarion system.
artifactId The ID of the existing Connection you want to use for this Jenkins Build.
jenkins.build.job.url The URL of Jenkins Job. You can copy-paste it from the browser (see
screenshot below).
jenkins.parameter.PARAM Parameters prefixed with jenkins.parameter. are passed to Jenkins at
each invocation of the Build.
polarion.parameter.PARAM Parameters prefixed with polarion.parameter. define a parameter to
configure Polarion's behavior.
When editing the configuration files, please make sure to escape the following symbols:
By default all build artifacts from Jenkins will be uploaded to Polarion. To upload only relevant files to
Polarion, a filter file can be defined using the Glob syntax.
Procedure
1. Create a file named build-artifacts.conf and add file filters using the Glob syntax.
Tip
Use Polarion's Repository Browser tool or your preferred Subversion client.
Caution
Do not use the Administration topic Building Descriptors to add the build.home.folder
to the configuration file. Adding it via the web interface has no effect, as it will be ignored.
Also, adding it in the New Build dialog box has no effect, as only parameters with the prefixes
jenkins.parameter. and polarion.parameter. are recognized there.
Polarion can launch Jenkins Builds that have been defined in Builds administration from the workflow
process of Work Items and Test Runs. Workflow actions can pass parameters to Jenkins, either from field
values of the Work Item, or the Test Run that the Workflow is run against.
In the relevant Workflow configuration (Work Item or Test Run), you need to define a workflow Function
named TriggerJenkins for a defined workflow Action that should trigger the remote build.
For both Work Item and Test Run workflows, define the following parameters for the TriggerJenkins
workflow function:
build.artifact.id (Mandatory) The ID of the Connection defined for the Jenkins Build the
workflow action will trigger.
build.descriptor.name (Mandatory) The name of the Jenkins Build the workflow action will trigger.
jenkins.parameter. (Optional) Where [PARAM NAME] is the name of a build parameter to be sent
[PARAM NAME] to Jenkins when the Build is triggered. .
The Jenkins integration also allows passing of field values of the Work
Item or Test Run to Jenkins. To do this, add the following to the value
of the parameter: ${fieldId}. For example, ${title} if you want the
title to be sent. Combinations of field values are possible. For example: $
{milestoneId}-${versionTag} or stage-build #${buildId}. If you
specify a nonexistent field ID, the workflow will fail. Comments, Attachments,
Linked Work Items, or other complex multi-valued fields are not supported.
Rich Text will be sent in its HTML representation.
The Jenkins integration also allows you to send Polarion build information
(build stamp, author, and project) to Jenkins.
${polarion.build.BUILD_STAMP}, $
{polarion.build.BUILD_AUTHOR}, $
{polarion.build.BUILD_PROJECT}
Caution
Parameters polarion.parameter.* and jenkins.parameter.* in the descriptor.xml file, or
configured during build creation, will be overridden by workflow parameters if any exist which have
identical names.
The following optional parameters are available for the TriggerJenkins function in Work Item workflows.
workitem.build.enum.field.id The ID of a field of type Build Enum that should be set to the Jenkins
build triggered by this function.
workitem.build.number.field.id The ID of a field of type String that should be set to the Jenkins build
number by this function.
workitem.testrun.enum.field.id The ID of a field of type Test Run Enum that should be set to the test
run ID created by the build triggered by this function.
Note
The workitem.testrun.enum.field.id parameter is ignored if more than one Test Run is created by the
build triggered by the workflow.
The following optional parameters are available for the TriggerJenkins in Test Run workflows.
testrun.build.enum.field.id The ID of a field of type Build Enum that should be set to the Jenkins
build triggered by this function.
testrun.build.number.field.id The ID a field of type String that should be set to the Jenkins build
number by this function.
Jenkins is frequently used to run automated tests. If such tests write test results to an xUnit file,
Polarion enables users to import the test results to existing Test Runs, or new Test Runs created by
the import process. The status of the Test Run after import is defined by the project's configuration
for automated testing in Administration Testing Configuration. For information, see topic
Automated Testing, especially the section Map Results of automated test to enumeration.
The following parameters must be set in a Jenkins Build, or in the Workflow configuration for the
workflow function TriggerJenkins:
The following regular xUnitFileImport job parameters (described in the Reference topic xUnitFileImport
job parameters) may also be used:
• polarion.parameter.maxCreatedDefects
• polarion.parameter.maxCreatedDefectsPercent
• polarion.parameter.templateTestCaseId
• polarion.parameter.templateDefectId
• polarion.parameter.idRegex
• polarion.parameter.groupIdRegex
Note
The polarion.parameter.idRegex parameter is silently ignored to be updated for existing Test Runs, as
the ID of a Test Run is a read-only attribute.
Tip
For this usage, the xUnit import parameters must be prefixed with polarion.parameter., as shown
in the above list.
Caution
The target Test Run, or the Test Run Template for a new Test Run, must not contain any Test Cases or
Test Records before the build is triggered. Also, the Test Case configuration must not require signatures
before test can be run. To be able to import test results from Jenkins Builds, users must have project
repository READ and WRITE access. See the first note in the Configure user permissions section for
more details.
After configuring Test Run workflow, test results from Jenkins can be imported into an existing
Test Run by simply triggering the workflow. For this to work, it is necessary that the parameter
polarion.parameter.xUnitFile is set either for the Jenkins Build, or for the TriggerJenkins action in the
Test Run Workflow.
A Jenkins Build can also trigger the creation of a completely new Test Run. This happens when both
the polarion.parameter.xUnitFile and the polarion.parameter.testRunTemplate build parameters are
set, and the build is triggered manually from the Builds page, or from a Work Item workflow. The
ID of the Test Run created is the Build ID of the Jenkins Build that created the Test Run. If the
polarion.parameter.testRunName parameter is set, the Test Run will have the title defined by this
parameter. Otherwise the name of the Jenkins Build will be used.
Note
• If multiple xUnit files are matched to the polarion.parameter.xUnitFile parameter when importing
xUnit test result files from Jenkins to Polarion Test Runs, one Test Run is created for each matching file.
• When the Test Run is updated with results from Jenkins from a Test Run workflow, the Test Run is only
updated with one of the matching xUnit files, even if there are more matching xUnit files.
• When importing test results from Jenkins to a new Test Run, setting custom fields with the Jenkins
Build (enum) and Jenkins build number (String) is not supported.
Tip
In order to update the status of the Test Run correctly when triggering Jenkins and importing test results
using a Test Run Workflow, make sure there is a Test Run Workflow transition from the initial status of
the function that triggers Jenkins, to the statuses that are defined in Administration Testing
Configuration.
For example, suppose you have a Test Run Workflow function that triggers Jenkins, which is configured
for the transition from a status named In Progress to a status named Tests Running. Furthermore, in
the testing configuration (see access point above) you have the following status mapping for Test Runs:
• Passed to Passed,
• Failed to Failed, and
• Error to Failed.
Then you would need to define arbitrary Test Run Workflow transitions from In Progress to Passed, and
from In Progress to Failed.
You can configure Polarion to trigger builds on a connected Jenkins system, schedule such builds,
associate a Jenkins Build with a Work Item, import test results from Jenkins Builds to new or existing
Test Runs.
You should already have at least one Connection and one Jenkins Build defined in your project
configuration.
Procedure
Build Artifact In the list select a Jenkins Connection to use for this Build.
Build Definition In the list, select a Jenkins Build definition.
Tip
The lists in the above fields display currently-configured Connections and Build definitions,
respectively.
You can associate Jenkins Builds with Polarion Work Items by means of a custom field of type enum/Build.
Procedure
1. In Administration Work Items Custom FIelds, define a custom field, of type enum/Build
and named Build, for every Work Item type you want to be able to associate with Builds.
2. In Administration Work Items Form Configuration Work Items Form Layouts, add the
custom field to the form layout for all work item types you want to be able to associate with builds.
Now it should be possible to associate individual Work Items with a Build.
3. To associate a specific Work Item with a Build, select on the Work Items page (Navigation Work
Items), and select a Build in the Build field, which should now appear in the Work Item's detail form.
Jenkins Builds can be scheduled to be run automatically. To configure this, open Global Administration
Scheduler and add an entry similar to the following example:
Attributes:
Troubleshooting
Issue: Jenkins Build is not shown in the Create Build dialog box invoked on the Builds page.
It is possible that entries in the Create Build dialog box do not appear if there are certain white spaces in
the files artifacts.xml or descriptors.xml. The safest to use are simple space characters. Also, please make
sure that <artifact> and <descriptor> elements are inside <artifacts> and <descriptors>
elements, respectively.
Tip
Depending Jenkins Build configuration, we recommend that you consider giving the users interacting
with them the following permissions:
For Example:
Triggering a Jenkins build from the Builds topic can (depending on the configuration), result in the
creation and execution of a Test Run. Similarly, the execution of a workflow from a Work Item can (also
depending on the configuration), result in setting a custom field of the Work Item. The user performing
these actions must have the corresponding permissions for everything that these actions result in.
DOORS
DOORS overview
Warning
Before importing, read the Import Limitations and Recommendations topic.
Connecting to DOORS:
The connection to DOORS only requires the ID used to identify the target DOORS database. The connection
is established from the DOORS client to Polarion by running a DXL script.
Note
You must configure a Personal Access Token (PAT) for the Doors connection first. See Import
prerequisites for details.
Click Connect to activate the connection and run the DXL script in a DOORS client (Tools Edit)
connected to the DOORS database containing the module you want to synchronize.
Note
• While the script is running, the DOORS client will be locked until you close the connection.
• Running the script from a Module can lock up the sync. (The Connector might attempt to close the
DOORS module.)
If you are planning to schedule the synchronization, run the DOORS client on a workstation where the
connection can be kept active.
General Setup:
When synchronizing with DOORS you typically want to synchronize Live Documents in Polarion to Modules
in DOORS and include the structure in the specifications. This will allow you to easily control the mapping
to Polarion Work Items, since they will be in the context of the Live Document you have chosen to
synchronize to.
To synchronize the structure, one sync pair must be defined per Module/Live Document pair. Make sure
that you configure the sync pair so that it points to a specific Live Document in Polarion and Module in
Doors. (See Configure a Synchronization Pair for details.)
There are two ways you can configure a DOORS sync pair:
a. Open the DOORS module you want to synchronize, go to Tools Edit DXL, then insert
following script and run it:
Module m = current
print qualifiedUniqueID(m)
b. Put the value you get after execution of the script in the appropriate field in the Doors Sync Pair
in Polarion.
2. Use the Module URL;
a. Choose the target module in Doors, then right-click to open the context menu and choose
Properties.
b. In the opened General tab click Copy URL beside URL.
c. Paste the value in the appropriate field in the Doors Sync Pair in Polarion.
Tip
Select the Use Title as Root option to sync Work Items below the first title in Polarion because it is
usually a better representation of a DOORS Module’s structure. If you have additional content below
the first title, depending on the synchronization pair settings, the sync operation may attempt to create
objects in DOORS to synchronize this Live Doc.
You can set the Creation and Hierarchy directions in the following ways:
Type mappings
Before beginning the mapping process, spend some time determining how you want the data mapped
between DOORS and Polarion. The Synchronization will not create Polarion Work Item types and fields
automatically. (They should all be created before you start mapping.)
The DOORS connector will treat objects without Object Text as Headings and other objects as
Requirements.
Since DOORS does not differentiate between different types of objects in a module, it’s common practice to
define the attribute type in DOORS.
These types can then be mapped via the Advanced type mappings dialog box.
3. All values of the selected attribute should now be available for type mapping.
Note
Mapping to the Work Item type heading will impose some limitations on the way that the structure can
be represented in Polarion.
Tip
You can always choose to use a Work-item of type called something like Doors heading to replicate the
DOORS structure verbatim inside of Polarion.
Field mappings will vary depending on your needs, but consider following DOORS-specific suggestions:
• When syncing any rich text attributes, you should also include attachments because the rich text fields
might include embedded objects.
• VERY IMPORTANT: Avoid syncing back Object Heading for Work Item types other than the Heading
type because Polarion will automatically populate the heading and returning these auto generated
headings might not be desirable.
The connector will use the name of a DOORS option for Value mappings. Define Value mappings
accordingly, especially when syncing an attribute to Doors. (Attempting to update an attribute with an
invalid value will fail).
Link mapping
Links can be synchronized from DOORS to Polarion by defining an attribute mapping from Relations to
Linked Work Items.
By default, the link created in Polarion will use the relates_to link role.
It can be configured by defining a value mapping from relates_to in DOORS to the link role you want to
use in Polarion.
Different roles can be used per Object or Work Item type by defining the attribute mapping for links in the
Type-specific Mapping section.
Limitations
• The limitations that apply to DOORS imports also apply to link mapping.
• Bidirectional synchronization of rich text can lead to loss of Polarion data because DOORS’ ability to store
rich text is very limited.
• Currently it is not possible to synchronize links added in Polarion to Doors.
• When adding .rtf files containing OLE objects in Polarion, syncing them to Doors results in the
reversion of an attachment with an adjusted name.
(<Doors Attribute> <Index>.rtf)
When configuring synchronization with DOORS as a scheduled job, you must keep the DOORS client
running in the background. It must be done on a workstation that can connect to the Polarion server and
the DOORS server. The DOORS server must also have the DOORS client installed on it.
The DOORS client can be executed as a scheduled job to ensure that the client is started automatically, in
case the workstation is restarted, or the Doors client crashes, for example.
Procedure
5. Name the task Doors Connections (for example), and set it to Run whether users is logged on or
not.
6. Click the Trigger tab, click New, select At Startup from the Begin the task drop-down menu and
click OK.
7. Click New again on the Trigger tab, select On a Schedule from the Begin the task drop-down menu,
click Daily set up a time like the screenshot below and click OK.
8. Both triggers should be listed and appear as Enabled in the Trigger tab.
The Polarion connector for Enterprise Architect (EAPO) allows you to publish models (or parts of your
models) to Polarion. This section covers help covers EAPO 3.x. Once a model is published, you can link
the Enterprise Architect (EA) model items to Requirement Work Items for coverage. All of your model
diagrams can be published to Polarion and you can export model tag-values to Polarion as specific
custom fields.
If EA items are changed, you can also update them in Polarion by re-exporting them.
You select which EA item to map to inside Polarion via a configuration mapping screen. (The
configuration is saved and can be reused for subsequent re-exports.)
You can also choose which part of a model you want to export. (Either the top root node or some
lower-level package.)
Once exported to Polarion, you can manage your EA items in Polarion like any other Work Item.
You can also view status updates or comments added in Polarion to exported EA items directly inside EA
with the Import from Polarion operation.
Main features:
• It is completely integrated with the EA interface. (Menu items, synchronization results, and the Polarion
browser are visible without leaving EA.)
• Easily toggle between EA and the Polarion web interface.
• No additional customization is required. (To either an EA model or the target Polarion project
configuration.)
• Mapping configuration and synchronization data are stored in an external database and not within your
EA or Polarion projects.
Extension Requirements
Note
See the System Requirements section for additional hardware and software requirements needed to
run EPAO.
Note
Ask your administrator for assistance with the recommended TLS version and see Add high transport
layer security.
RAM:
• 2 gigabytes or more
• 10 megabytes
Requirements
• You already have Polarion 20 R1 (or newer) installed, configured, and running with the required ALM
license.
• EA 15.x (or newer) is installed.
Note
The most update-to-date information about the requirements needed to use the Polarion Connector
for EA, including software versions, add-ons, and licenses, is maintained in the Requirements on the
Connector's page on the Polarion Extensions portal.
Procedure
Before you can export an EA model to Polarion, you must configure the connector.
Make sure that Direct SVN access is enabled with the following settings:
<Location /eapo_repo>
DAV svn
SVNPath "[Polarion_Home]/data/svn/repo"
SVNAutoversioning on
AuthzSVNAccessFile "[Polarion_Home]/data/svn/access"
Require valid-user
AuthType Basic
AuthName "Subversion repository"
AuthUserFile "[Polarion_Home]/data/svn/passwd_credentials"
</Location>
The EA connector also requires that you create a custom Work Item type with an ID called Heading inside
the Polarion project you wish to export to. You cannot export models without first creating this custom
Work Item.
This custom Work Item is required to maintain the model hierarchy correctly inside Polarion.
Tip
See Configure Work Item types in Polarion Help if you do not know how to create one, or talk to your
Polarion administrator.
There are two ways to visualize exported objects from Enterprise Architect in Polarion:
You can use any project to export Enterprise Architect objects to Polarion without specifying additional
custom fields in your Polarion configuration. Instead, EAPO exports the objects by adding a rich table with
Enterprise Architect fields to the Polarion Description field. (See screenshot below.)
If you set up specific custom fields in Polarion, EA items are exported to these custom fields and are more
readable in Polarion. (See screenshot below.)
EAPO comes with a custom field XML definition file that you can load in a Polarion project or default
configuration. (See Customize Project Templates.)
If you add these fields, the Polarion Description field only populates with a simple table (in the case of a
diagram) or simple text. (The defined custom fields populate with Enterprise Architect field values.)
Tip
Use this method if EA information is not required or should be reorganized or hidden.
Export to Polarion
Procedure
1. There are two ways to launch the Polarion connector for Enterprise Architect:
a. Select the Specialize tab on EA's top menu bar Polarion Integrator Export to Polarion.
Note
When using this method, the entire EA model is in scope and used for export.
b. Select an item from the model tree, right-mouse click Specialize Polarion
Integration Export to Polarion
Note
Use this method when you only want to export a part of your model, such as a particular
package. For example, if you just wanted to export the Use Cases package, select your target
package, right-mouse click Specialize Polarion Integrator Export to Polarion.
Tip
We strongly recommend that you only export parts of the model you need inside Polarion. This
helps with the overall useability and performance of the connector. It also ensures that Polarion is
not populated with unnecessary EA model information.
(This is where you specify the Polarion server and project you want to export the model to.)
2. Enter a Server Url. It can be "http" or "https" (without /polarion at the end of the string).
a. For HTTP:
b. For HTTPS:
Tip
• When using https, please make sure that the Polarion server is configured to use TLS 1.3
or lower.
(Always use TLS 1.2 or TLS 1.3 to achieve higher security, and try to avoid using the system
default TLS 1.0 and TLS 1.1.)
• Ask your administrator for assistance with the recommended TLS version and see Advanced
security configurations for more information.
3. Enter a Server Port. The default is 80 but you can specify another port.
4. Enter the SVN repo URL. It can be specified if different, but by default it is repo/.
5. Enter the target Project ID. This should be specified as the ID, not as the Polarion project name.
6. Enter a Polarion Username and Password.
Enter a Polarion user with an ALM license and the permissions required to create Work Items for the
target project.
This user is identified as the object's creator in the project.
7. (Optional) Select Save connection to reuse, then click Test connection.
Tip
We recommend that you save and test your configuration before proceeding.
Procedure
ii. Select a location for the database on your local machine and enter a name for it.
(The connector adds the .sdf file extension so do not include it in the name.)
b. Select an Existing Mapping.
You can use an existing database mapping to update elements that are already in Polarion or
add others.
2. Click Next >>.
The main mapping window is where you map Enterprise Architect elements to Polarion Work Item types.
Note
Take note of the tree's starting point. If you want to select only part of a model, it should be the topmost
point. (Alternatively, the top would be the root node of the model.)
1. Click on the fourth column to select a Polarion Work Item Type from the drop-down list.
(Available Work Item types are taken from the Polarion project you selected earlier.)
Note
If you did not create a custom Heading Work Item, you would not be able to continue the
mapping process.
2. Confirm if you want to map all elements with the selected Enterprise Architect type and stereotype to
the same Polarion type.
a. Click Yes if you want to automatically select and map all EA objects with the same type and
stereotype to the same Polarion type.
b. Click No to only map the selected EA object with the selected Polarion type.
c. Click Advanced mapping to define the relationship between the following:
EA Tagged values
Polarion Custom Fields (for the selected type)
Tip
To avoid errors, disable all Required fields, Categories, and other potential constraints on the initial
Status of the selected Polarion Work Items before exporting from EAPO.
EAPO exports all selected elements to Polarion. (This can take a while, depending on the number of
selected objects.)
Export completed
EAPO exports all selected EA elements to Polarion. When complete, EAPO displays a summary result table
with nine columns.
• Created
• Updated
Operation Result Operation results:
• Success
• Failed
Open in EA Click to open the corresponding object in EA. If the object is a package or
an element, it is selected on the project tree. If the corresponding object is a
diagram, EAPO will open it in visualization.
Open in Polarion Click to open the corresponding object in Polarion. Then, EAPO opens the item
in the user's favorite web browser.
Re-export to Polarion
You will likely make changes to your model, including diagrams, and these changes will need to be
re-published to Polarion.
The process of re-exporting is the same as the initial export operation. Simply select the same database
file you used for mapping used for that export.
Any EA model element exported to Polarion then linked to other Polarion Work Items maintain their links
on subsequent re-export operations.
Limitations
• You cannot change the mapping of already exported EA model elements. However, if you have new EA
model element types, you can map them to new Polarion Work Items.
• If you delete model information, model elements, or diagrams, they are not automatically deleted in
Polarion. You must manually delete them.
With EAOP, you can import updates from any Polarion EA model items you previously exported. Updates
can include Work Item Status changes and Comments.
Procedure
1. There are two ways to launch the EAOP to import from Polarion:
a. Select the Specialize tab on EA's top menu bar Polarion Integrator Import from
Polarion.
Note
When using this method, the entire EA model is in scope and used for import.
Note
Use this method when you only want to import a part of your model, such as a particular
package. For example, if you just wanted to import the Use Cases package, select your target
package, right-mouse click Specialize Polarion Integrator Import from Polarion.
Here you can add information about the Polarion endpoint server for the connection.
Tip
• When using https, please make sure that the Polarion server is configured to use TLS 1.3 or
lower. However, always use TLS 1.2 or TLS 1.3 to achieve higher security, and try to avoid using
the system default TLS 1.0 and TLS 1.1.
• If you saved your configuration when you exported to the same Polarion server and project,
select it under Saved connection.
(Or fill out the Polarion server details, click Test connection to ensure that it works, and select
Save connection to reuse.)
• Package: The folder that brings elements together and logically divides
them.
• Diagram
• Element: The atomic EA object.
WI New comments The number of new Comments added to the Polarion Work Item.
WI New status A Work Item's current Status.
(Only displayed if the Status was changed since the object was created or
since the last synchronization.)
Polarion type The Polarion Work Item type ID of the created element.
Open in EA Click to open the corresponding object in EA. If the object is a package or
an element, it is selected on the project tree. If the corresponding object is a
diagram, EAPO will open it in visualization.
Open in Polarion Click to open the corresponding object in Polarion. Then, EAPO opens the
item in your default web browser.
Known Limitations
• If you cannot load EAPO in Enterprise Architect, make sure that the permissions on the internal database
file are set to read and write for all users.
Internal database file location:
C:\Program Files (x86)\Polarion AG\EAPO Enterprise Architect Connector
Pro\Polarion\Internal\Storage.sdf
Right-click on the database and assign read and write permissions to Everyone.
• Sometimes Test connection can take a while.
◦ Ensure that your Proxy configuration is correct and that the Polarion project ID is correctly specified.
◦ EAPO only works with the Polarion project ID, not the project Name.
• When using https, please make sure that the Polarion server is configured to use TLS 1.3 or lower.
However, always use TLS 1.2 or TLS 1.3 to achieve higher security, and avoid using the system default
TLS 1.0 and TLS 1.1.
EAPO Troubleshooting
To configure EAPO in debug Mode (so that you get a verbose log in the log file), add an isDebug.txt file to
the EAPO log folder.
Example
If your install path is:
C:\ProgramData\EAPO\ [EAPO.txt]
Connection settings
When configuring a connection to OpenText ALM / Quality Center, you can optionally specify a direct
connection to the SQL database using JDBC. While this connection is optional, it is not possible to access
(read/write) links from tests to requirements, and between requirements, without it.
To successfully connect, you must specify a value in the JDBC Connection String. This value can be
derived from the Connection String in the DB Servers tab of OpenText ALM / Quality Center's Site
Administration. When you enter the string into Polarion, replace mercury with jtds (for a Microsoft SQL
database), or oracle:thin (for an Oracle Database).
Filter (HPQC):
A filter in OpenText ALM / Quality Center can be used like a Work Item query to filter entities in OpenText
ALM / Quality Center.
Example
A filter with only entities with IDs between 5 and 10 would be: id[>=5 And <11].
For example the query id[>3] AND title['foo ba*'] is a valid query to filter out all entities with an
ID larger than 3, and a title starting with foo ba.
Tip
To set up filtering in OpenText ALM / Quality Center, use the SQL column ID for the field_id.
See the ALM REST API Reference Documentation for more information.
Parent ID (HPQC):
The ID of an entity in OpenText ALM / Quality Center, that will be used to define a root element
in OpenText ALM / Quality Center. Every entity from Polarion will be put below this root element in
OpenText ALM / Quality Center, and only entities that are below this root element will be transferred
from OpenText ALM / Quality Center to Polarion.
The parent ID can only be used for the "Requirement" OpenText ALM / Quality Center entity type, since its
the only element that supports hierarchies.
Jira
Jira overview
Sync Jira Versions to ◦ Polarion 2304 supports Jira Server LTS 8.20.x and 9.4.x
Polarion Plans ◦ Polarion 2310 supports Jira Server LTS 8.20.x and 9.4.x
Sync multiple Jira projects ◦ Polarion2404 supports Jira Server LTS 8.20.x, 9.04.X and 9.12.x
Connect to Jira with a
personal access token
The following special conditions apply when connecting to a self-hosted server or cloud based Jira
instance.
Procedure
1. When attempting to connect to a Jira cloud instance with single sign-on (SSO) or basic authentication
you must use an API Token as your password. (See https://confluence.atlassian.com/cloud/api-
tokens-938839638.html for details.) Jira no longer supports the use of primary account credentials
(like passwords) for basic authentication. (See https://developer.atlassian.com/cloud/jira/platform/
deprecation-notice-basic-auth-and-cookie-based-auth/ for details.)
2. When attempting to connect to a self-hosted Jira server instance with SSO you must configure your
Jira server and SSO with the auth_fallback option. For details, please check the documentation
for Jira and the SSO product you use.
Note
Once the above has been configured, Jira can fall back to local account passwords for
authentication and the Jira / Polarion connector will be able to authenticate correctly.
3. When attempting to connect to a Jira server instance with mutual or two-way authentication you
need a keystore with a client certificate.
a. Create a new keystore from the Jira client certificate with the same password as the certificate's
password.
b. Create a new entry in the user account vault of Polarion with the same password.
Note
You can define settings for several servers. Each server setting is separated by a semicolon and the
configurations of each server setting are separated by a comma. You must use either the .jks
or .pkcs12 file formats for the keystore.
Examples:
com.siemens.polarion.jiraconnector.connectionCheckMutualTls=https://my-
first-jira-server.de/,
/opt/polarion/my-keystore.jks,first-jira-alias,first-jira-vault-
user;https://my-second-jira-server.de/,
/opt/polarion/my-second-keystore.jks,second-jira-alias,second-jira-vault-
user
Caution
This may have security ramifications for your Jira project and you should implement the following
security tips:
• Only allow local Jira user accounts for people who need access to all Jira projects as well as the
Polarion integration.
• If you want greater access with more control, then set up special local accounts that can only access
your target project.
JQL Query (Jira): A JQL (Jira Query Language) query can be used like a Work Item query to filter entities in
Jira.
For the JQL Syntax please consult the official Jira documentation under https://confluence.atlassian.com/
display/JIRA/Advanced+Searching.
Jira Formatting - (What's preserved and omitted when a Jira project is synchronized):
When synchronizing rich-text from Jira to Polarion, the Connector will use the conversion to HTML
provided by Jira. This will accurately render the rich-text in Polarion for most Jira formatting, including
all of the formatting listed below.
When synchronizing rich-text from Polarion back to Jira only the formatting listed below will preserved. (All
other formatting will be removed.)
Note
• The icons for Attachment links in Polarion's Description field are lost when syncing with Jira. (The
links remain intact.)
• The icons for Work Item links are preserved.
• When syncing back from Jira Polarion the icons and links are preserved on the Polarion side.
Character Formatting
Preserved
+ Underline
* Bold
_ Italic
- Strike-through
(/) Icon check
(x) Icon failed
(i) Icon information
?? Citation
^ Superscript
~ Subscript
{quote} Block-quote
{color} Text color
• Tables
• Images and image references. (If you want to make an image reference on the Polarion side, the
attachment link should have same label as its file name.)
Note
Formatting omitted:
• All other Jira formatting that is not listed in the above table.
• All formatting done within Microsoft Word.
• Formatting changes within a single word. (For example, Polarion)
• Formatting that begins in the middle of one word and ends in another. (For example, polarion alm
tool.)
Assigning User Stories to Epics is common practice in Agile projects. Polarion and Jira do this in different
ways:
• In Polarion it's usually done by using a link role like Parent or Implements.
• In Jira, it is done using the Epic Link field.
If you are synchronizing both Epics and User Stories between Polarion and Jira, you'll probably also want to
synchronize the links between Epics and Stories.
Procedure
1. Add a field mapping in the type-specific Field Mapping section for User Stories.
Warning
If you sync Jira Epics with a team-managed project in Jira cloud, please do not map Jira's Epic
Name field. Use the Summary field instead.
Warning
• Make sure that the link role is configured in Polarion and LINKED_EPIC is in all caps.
• Polarion only supports Parent Link synchronization from issue types on the Story level to issue
types on the Epic level.
You can also synchronize Jira links (both regular and Epic) to hyperlinks in Polarion:
Procedure
1. First, define an Attribute Mapping from Links to Hyperlinks. (Unidirectional – From Right to Left.)
2. Then define a Value Mapping for each link type that you want to synchronize with Polarion, mapping
the link type to a link role defined in Polarion.
Beginning with Polarion version 20 R1, changes were made to Polarion's support of mapping of Sync Pairs
for Jira Cloud, due to changes in the Jira Cloud REST API. New Sync Pair mappings to Jira Cloud should
observe the new field naming, described below. Existing mappings will need to be changed or replaced.
Note
Currently, only mappings to Jira Cloud are affected. On-premise installed versions of Jira are not
affected, and no change to existing mappings is necessary.
The name field of the User object is not present in the Jira Cloud API now. It is replaced by field accountId.
You can make this change in your existing mapping configuration(s) by editing the relevant Sync Pair(s)
in Polarion project Administration, or in the underlying configuration file <project_directory>/.polarion/
synchronizer/configuration.xml.
Tip
Because of the different ways that Jira and Polarion represent comments, we highly recommend that you
provide value mappings if you want to synchronize them.
(Jira Username is the content of the name field of the Jira comment author in its JSON representation.)
polarionUserID accountId
(accountId is the content of the accountId field of the Jira comment author in its JSON representation.)
Caution
Due to this major GDPR related change in Jira cloud, new value mappings must be added if you
configured them before the GDPR Jira update. In addition to the existing mappings (for example,
polarionUserId Jira Plain Name) you must also add an accountId mapping on the Jira
side.
For example:
syncUserId abc456:1abc1234-abcd-1234-12cd-abcabcabcabc
johnDoe 123456:a1234567-1234-abcd-ab34-123123123123
• Comments cannot be edited in Polarion. If a comment is edited in Jira, it will be synced to Polarion as a
new comment.
• Comments cannot be deleted in Polarion. If a comment is deleted in Jira, it will remain in Polarion.
• Replies to comments in Polarion will be synced to Jira, but they appear with two asterisks and are not
visually associated to the comment they reply to.
• Rich text comments in Jira are synced to Polarion but appear in low-level formatting. (For example,
*Bold text*, +underlined+ )
Supported fields
Note
Synchronization of the Time Spent field is only supported from Polarion Jira.
Custom Field Name in Jira Jira Custom Field Jira Custom Field Type (internal)
Type
Checkboxes (single) array/option com.atlassian.jira.plugin.system.customfieldtype
s:multicheckboxes
Checkboxes (multi) array/option com.atlassian.jira.plugin.system.customfieldtype
s:multicheckboxes
Associating Polarion Work Items or Jira Issues with a plan for a release or iteration is realized in different
ways in Polarion and Jira:
• Polarion uses Plans, which, for example, might represent iterations or releases. Work Items are
assigned to a Plan using the Planned In field of the Work Item.
• Jira uses Versions, which can be assigned to Issues using the Fix versions field.
Polarion can use the information in the Planned In and Fix versions fields to automatically create, update
and delete Plans in Polarion, and Versions in Jira. It is not necessary to create and map them manually.
This implies it is not possible to map them manually.
Note
On the Jira side, currently only the Fix versions field is supported. It is not possible to sync Jira Versions
assigned to the Affects Versions field.
You need to create a Sync Pair to synchronize Polarion Plans and Jira Versions. Please note the following
prerequisites:
Create a Sync Pair for synchronizing Polarion Plans and Jira Versions:
This Type Mapping enables the synchronization of Plans on the Polarion side and Versions on the Jira
side. Without it, no Versions in Jira are created, even if Work Items have Plans assigned, and vice
versa.
• Jira Versions are only created for Polarion Plans that are assigned to Polarion Work Items in the
sync scope.
• Polarion Plans are only created for Jira Versions which are assigned to Jira Issues in the sync scope.
2. Configure Attribute Mapping from type Plan to type Version.
Mapping the Plan Name field to the Version Name field is mandatory. Without this mapping,
synchronizing Plans and Versions is not possible.
With the type mapping from Plan to Version, the Planned In and Fix versions fields are mapped
implicitly. The Fix versions field on the Jira side will still be available in the Sync Pair configuration if
you want to sync Fix versions as enumeration values.
• It is not possible to map existing Plans to existing Versions, and vice versa.
• The propagation direction of Polarion Plans and Jira Versions and their associations with Work Items
corresponds to the Propagate new items setting in the General Settings of the Sync Pair.
• You have to sync at least one field of the type which holds the Planned In/Fix versions field
Bidirectional to trigger the creation of the Plan/Version and the assignment of the Work Items/Issues.
You can use the Type field to avoid unwanted changes on either side.
Caution
If Propagate Deletes is enabled, then deletion of a Plan will result in deletion of the corresponding Jira
Version, and vice versa. But simply unassigning Plans or Versions from Work Items will not result in
deletion of the corresponding Plan or Version on the other system.
Creating multiple SyncPairs for different Jira projects while using the same connection is only possible if
the sync direction goes from Jira to Polarion. Polarion to Jira and bidirectional sync is not possible in this
case.
Example
Executing SyncPair1 creates Issues in Jira project1 connected to the Work Items of Polarion
project1. These connections are saved in the Synchronizer Database.
Executing SyncPair2 after SyncPair1 does not create Issues in Jira project2, because the
connections for the Work Items of Polarion project1 already exist in the Synchronizer Database.
If you want to sync the same Polarion project to multiple Jira projects, you have to use multiple
Connections.
Example
Executing both SyncPairs creates Issues in both Jira projects, because different Synchronizer Databases are
used for different connections.
Note
You have to use the same connection for syncing if you want to preserve links between the Work Items.
You can create a connection to a Jira server using a personal access token.
• Jira on-premise
• Jira Cloud
Note
You must use the personal access token as the Password of a user/password connection for Jira Cloud.
Procedure
b.
5. Enter the token generated by the Jira Server and click Create.
Note
Select User instead of Token to connect via a user and password.
Procedure
MATLAB Simulink
Overview
The new Polarion Connector for Simulink allows for a much-improved user experience over earlier
versions of the Connector. For the first time, Polarion itself has been directly embedded into the Simulink
desktop client to support a larger set of customer use cases and reduce inconvenient App context
switching.
Another first for the new Connector is that it works with the Requirements Toolbox. Users can use the
popular drag and drop approach to create traceability between Requirements and model elements. Then
depending on the Connector settings, surrogate Simulink items can be created in Polarion for any linked
model elements. These surrogate Simulink items are rich in information too, with block parameter data
and, where applicable, model diagrams. The integration also automatically links the surrogate Simulink
items back to original Polarion Requirements.
As with earlier Connector releases, you can navigate from Simulink model elements to its associated
Polarion Work Item and vice versa.
Extending the supported use cases even further, users can work with Polarion LiveDocs directly or
across the entire Polarion project scope. When working with Polarion LiveDocs, it is possible to
work with document baselines or earlier revisions.
We also simplified setting up the Connector to work with multiple Polarion servers or multiple projects
within each server. A Polarion project can also work with multiple Simulink models at once.
To maintain backward compatibility with earlier Connector releases, the new Connector also supports
publish and direct linking to existing Polarion Work Items and Requirements. This mode can work with
or without surrogate Simulink items.
We have also added the ability to link Simulink blocks to a newly created Work Item on the fly. This
means you can take advantage of Polarion's powerful task and defect/issue management capabilities to
create, for example, defect/issue Work Items against your model and link those Work Items to specific
model elements.
The Connector also works with Simulink Test. This allows you to import Polarion Test Case specifications
into Simulink Test as Test Cases. If Test Cases are linked to Requirements, then these are automatically
linked in Simulink. The Polarion Test Case specifications can be further modified and re-imported into
Simulink Test to reflect any changes. The Connector also supports the execution of Simulink Test Cases and
the collection and import of Test Results into Polarion as Test Records.
The new Connector works with the 2021b Simulink Family onwards, (including Simulink, Stateflow, and
System Composer), and requires the Requirements Toolbox as a minimum. If you also want to work with
testing, then Simulink Test is required.
Tip
See Linking schema to understand how the Connector handles links with or without surrogates in both
Requirements Toolbox and Simulink Test mode and Direct Linking mode.
Here is how you set up a connection between a MATLAB installation and a Polarion server.
Requirements
• You already have Polarion installed, configured, and running with the required license.
• Matlab Simulink 2021b or newer. (Windows & Mac)
• Simulink Requirements Toolbox
• The most current information about the requirements needed to use the Polarion Connector for
Simulink including software versions, add-ons, and licenses, is maintained in the Requirements section
on the Connector's page on the Polarion Extensions portal.
Note
The Polarion PRO license is supported. The Polarion Reviewer license is not supported, because it does
not allow users to create new Work Items.
Note
If your Polarion server is configured for SSL you must import a certificate to the Java Keystore before
using the Polarion Connector for Simulink.
(Only applicable for self-signed certificates. If your server is configured publicly issued SSL certificates,
then you do not need to do this.)
See the Configure SSL and Import a certificate to the Java Keystore sections in Polarion's Help on
Support Center for details.
Procedure
Tip
• You can also run this script directly if you run it without the parameters from the MATLAB
Console.
• You can also use the script's source (in the root folder of the Connector installation package) to
automate or customize this process.
• If the Connector does not see an SSL certificate it will prompt you import the certificate using the
script.
2. Restart MATLAB.
Procedure
1. Export the certificate from the Polarion server with your browser and place it on the MATLAB-client
machine.
(Click the lock-symbol next to the URL address in Chrome, Edge or Firefox.)
2. Set JAVA_HOME (if not already set).
Example: set JAVA_HOME="C:\Program
Files\MATLAB\R2021b\sys\java\jre\win64\jre"
3. Import a certificate into the correct CACERTS file using the keytool executable:
%JAVA_HOME%\bin\keytool -importcert -file xxxxx -keystore cacerts -alias
"Polarion UAT"
4. Restart MATLAB.
Note
Uninstall any previous versions of the Connector before installing this version.
Procedure
Note
MATLAB might warn you: MATLAB cannot run this file because <some file>
shadows it in the MATLAB path. Select the Change Folder or Add to path options to
continue.
5. The Connector is installed and the following is displayed in MATLAB's Command Window:
When you run the installation program for the first time, it might display additional instructions on
how to extend your existing environment (If you already have startup.p files in your paths).
6. You can now see the button on the top right when you open or create a Simulink model.
Note
If you create a new model, save it before trying to use it with Polarion.
Next steps
Procedure
1. Configure a connection between your Polarion server and your MATLAB installation.
2. (Optional) Set up any required advanced configuration settings.
3. Decide how you want to work. Use Requirements Toolbox and Simulink Test mode mode or Direct
Linking mode.
4. If you plan to use Surrogates in your Polarion project (the default configuration), create or ask your
administrator to create a new Work Item Type in Polarion for surrogate Simulink items. By default,
the Work Item type for surrogates is simulinkitem. This can be changed and configured in the
Configuration.m file. (See the Advanced settings section for details.) If you do not know how to
create new Work Item Types in Polarion, see the Configure Work Item Type section in Polarion's Help
on Support Center.
By default, when a surrogate is created in Polarion, a configurable custom field called simulinkType is
used to describe the Simulink model element type in the Work Item. This custom field is initially defined
as a string, however, you can configure this in Polarion to be an enumeration instead. A script is provided
in the Connector's installation folder to extract all the model element types from your model and create a
file which can be imported into Polarion. This file can also be used for defining an enumerated list for the
simulinkType custom field. See Advanced configuration options for more information.
The Connector integrates Polarion directly in Simulink via a dedicated window. You can edit and import
Polarion artifacts right within Simulink.
Switch between Requirements Toolbox and Simulink Test Traditional Polarion view.
and Direct Linking modes.
The pin icon in the top right corner of the Polarion window enables you to pin or unpin the window.
When pinned, the Polarion window remains visible if you open other Simulink windows or views.
Connector Panes
Upper: Mode/settings/actions
Once you open the Polarion pane in Simulink, you have two modes to choose from:
Here you can import Polarion Requirements contained in a LiveDoc or an entire Polarion project. (You
can even filter them based on queries.) Once imported, you can link those requirements to blocks (your
model) and publish that information back into Polarion so that the original Requirements in Polarion
point to the linked model elements. (They link back to Simulink using hyperlinks.)
You can also work with Polarion test artifacts and Simulink Test Management. You can import Polarion Test
Cases into the Simulink Test Manager, execute tests, and report results back to Polarion.
Direct Linking Mode lets you link a Simulink block to a new Polarion Requirement that you can create
during the procedure, to an existing Requirement, or you can publish the block itself to Polarion. You
can also create a new Work Item during the process.
The Context view is a standard Polarion view without the left-side navigation pane or header.
By default, to help maximize real estate in the Polarion pane, we do not show Polarion's typical, left-side
navigation pane and header. To select different LiveDocs or the table/tracker project views, click Select
Polarion Context in both Requirements Toolbox and Simulink Test or Direct Linking modes.
However, sometimes you may wish to show Polarion's navigation pane and header. The Connector lets
you toggle between showing or hiding them.
• If the Polarion navigation pane/header are not visible, but you wish to see them, click Show/Hide
Navigation.
• If the Polarion navigation pane/header are visible, but you wish to hide them, click Show/Hide
Navigation.
• In some rare instances, you may need to click the button twice to get the desired effect.
Settings
Before you can connect to a Polarion server, you must configure it in Settings.
Tip
This is also where you go to:
• Select the Polarion Projects that users can import from when they click Select Polarion Context.
• Disable an existing server.
Click Collect Diagnostic on the bottom left if you experience connection issues.
This generates a file you can provide support to help solve the issue.
The Connector works with multiple Polarion servers (instances) and multiple Polarion projects on those
servers.
Multiple Simulink models (clients) can also work with Polarion projects.
Procedure
Tip
If your connection is a variant of an existing connection, select the connection and click Duplicate.
Tip
Personal Access Tokens (PATs) offer a convenient way to authenticate rather than relying on user
passwords that may change over time.
a. Authenticate using Credentials: Click Use Credentials, and enter the Polarion user's password
in the User Password field.
See the Polarion documentation that explains how you generate a PAT for your user account.
7. Enter an alias name in the Alias Name field.
(This name for the connection appears in the Configurations section on the left.)
Note
Avoid non- ASCII characters in the Alias Name because, by default, the alias is also used in
automatically generated file names for ReqSets and Test Files and may cause traceability issues.
You're now ready to start adding the Polarion projects you want to work with.
Tip
Right-click and Run importCert.m if there is no way to establish a secure connection between
Polarion and MATLAB. (The installation is disrupted by a HandshakeException.)
• You can also run this script directly if you run it without the parameters from the MATLAB Console.
• You can also use the script's source (in the root folder of the Connector installation package) to
automate or customize this process.
Procedure
Tip
Click Duplicate to copy an existing server's settings and modify them.
Procedure
Once you have configured a Polarion server, you can select the Polarion projects that users can import
from when they click Select Polarion Context.
Procedure
2. Click Settings.
The Polarion Settings dialog box appears.
3. Select your target Polarion server in the Configuration List on the left.
Tip
Enter text in the Search field to filter the results.
6. Click Save.
What to do next
Tip
You might want to check out the advanced settings before getting down to work.
Advanced configuration settings let users control certain aspects of the Connector's behavior. You
configure them by editing the Configuration.m file within the MATLAB editor.
Tip
The Configuration.m file comments explain what each property does, but here are a few that you may
want to focus on initially. Please note that after editing this file, you must run the Configuration.reset
command. If you have enabled or disabled Test Support, changed the Toolbar appearance, or changed
the URL of the Connector page, be sure to close and re-open the Polarion pane for the configuration
setting changes to take effect. (Or, you can restart MATLAB and Simulink.)
• CreateSurrogatesForBacklinks
◦ When you create links to your Polarion Work Items by either using Requirements Toolbox and
Simulink Test or Direct Linking modes and subsequently update the backlinks back to Polarion, this
option controls whether surrogate Simulink Items are created in Polarion.
You then end up with requirements linked to model blocks in Simulink and model blocks linked to
requirements defined in Polarion Work Items. This lets you do coverage in both tools. Surrogates
also apply to Simulink Test Cases where Test Cases defined in the Simulink Test Manager can be
represented as surrogate Test Cases in Polarion.
Tip
◊ You can opt to use surrogates for backlinking to Polarion in both operating modes. In Direct
Linking mode, this is a new functionality that was not available in the original Connector.
◊ If you plan to work with historical or baselined versions of Polarion LiveDocs, you should set this
option to true. Otherwise, you cannot store backlinks from Polarion to Simulink.
◊ Still not sure about the difference between linking with or without surrogates?
See the Link Schema diagrams for details.
◦ When set to "true" (the default), backlinking creates surrogate Simulink items for those Simulink
blocks inside of Polarion, and then links from those surrogate Simulink items back to the original
Work Item in Polarion.
The type of surrogate Simulink items created by the process is defined in the SurrogateItemType
= 'simulinkitem' option.
◦ SurrogateItemType
This is the ID of the Work Item Type in Polarion that will be used to create the corresponding
surrogate Simulink items.
◦ When set to "false", Polarion won't create surrogate Simulink items when processing backlinks.
Tip
If you are accustomed to the way the original Connector worked, setting this option to "false"
more closely mimics that behavior. The default "true" value is more oriented toward working in
Simulink Requirements mode.
◦ You can define the Polarion link role by changing the value in the following option:
SurrogateLinkType = 'implements'
The value must correspond to the ID of a link role as defined in the project configuration of the
Polarion project. ( Administration Enumerations workitem-type-enum.xml)
• MinimalisticToolbar
If set to "true", the Polarion pane toolbar icons are minimized. (Set to "false" by default.)
• MarkSurrogateSuspectOnChange
If set to "true", when surrogates are updated by backlink processing, where the Simulink item
changed, the outgoing link will be marked Suspect inside of Polarion.
• RequirementTypeMapping = containers.Map(... {'heading', 'epic',
'release' }, ... {'Container', 'Container', 'Informational' } ... );
By default, the Connector now imports LiveDoc Headings as Simulink Container type requirements.
Simulink requirements offers three different types: (Informational, Container and Functional)
You can map Polarion Work Item types to Simulink Requirement Types.
Example
Let's imagine you had an Information Work Item type in your LiveDoc.
RequirementTypeMapping = containers.Map(...
{'heading', 'epic', 'information' }, ...
{'Container', 'Container', 'Informational' } ...
);
When you import this Work Item into Simulink, you will see the Informational type set for the
requirement.
Configuration Properties
The table below lists and describes all the configuration properties available in the Configuration.m file.
Property Description
startPage The Connector's start page. This page opens when
you start a new session of MATLAB and open the
Connector's side panel. The setting screen changes and
allows you to specify the personal access token (PAT).
ReqSetFileNameFormat The definition for ReqSet name.
RequirementTypeMapping Mapping of Simulink Requirement types to Polarion
Work Item settings.
PolarionFieldsToBeImported Specifies which Polarion fields (pre-defined or custom)
are imported into Simulink Requirements.
PolarionFieldsPrefixInSimulink Specifies which prefix to use for Simulink attributes to
avoid any clashes with reserved names.
ProcessJustifications Enables the processing of Justifications stored in the
same ReqSet in which the Polarion Requirements are
stored.
Property Description
the block type and label, and labelOnly, which only
displays the label.
CreateSurrogatesForBacklinks Turn on or off the creation of surrogates inside Polarion.
SurrogateItemType The default Work Item type for surrogates.
SurrogateLinkType The default link role for links between surrogate and
original Polarion requirements (Work Items).
SurrogateLinkMapping The mapping configuration for SurrogateLinkType.
TypeCustomFieldID Specifies the custom field name for the surrogate Work
Item. If this parameter is left empty, then there is no
type exposed. When in use, this field is initially set up as
a string, however, it can be set as an enumeration for
faster processing.
Note
You may consider using the provided customizations/
generateTypeEnumeration.m script to create an
enumeration definition. That definition can then be
uploaded to Polarion. For further information, see the
built-in documentation of the script and the Configure
Enumerations section.
Property Description
have mixed LiveDocs with Requirements and Test Cases,
ignoring Requirements might also be helpful.
TestFileNameFormat Specifies the composition of file names for the
Test Files in the Simulink Test Manager. See
ReqSetFileNameFormat for the definitions of macros.
ProcessSimulinkTestCases Specifies whether Simulink Test Cases that are linked
to the Requirements have to be processed. If
enabled, linked Test Cases are created as surrogates
in Polarion, with the TestSurrogateItemType
linked with TestSurrogateLinkType to the original
Requirement.
TestRunTemplate New Test Runs from Simulink are created on top of this
template.
TestSurrogateItemType A type of item in Polarion that represents
Simulink Test Cases. It is used when
CreateSurrogatesForBacklinks is set to true.
TestSurrogateLinkType A type of link between simulinktestcase and the
original Requirement in Polarion.
ReportTestCasesResults If enabled, both action buttons to run linked Test Cases
with the Simulink Test Manager and to report results as
new Test Run(s) in Polarion are displayed, and Polarion-
relevant Test Case results can be collected from Simulink.
As a prerequisite, the ProcessSimulinkTestCases
option has to be set to true.
TestResultsMapping The mapping table between the Simulink Test Case
results and Test Record results in Polarion. This is only
used if ProcessSimulinkTestCases is enabled.
Note
The Test Run itself is only marked as passed if all Test
Cases return passed as the execution result.
Property Description
By default, the integration may add white space
characters to the file name based on the Polarion
document name. Therefore, if the configuration property
is not defined or is empty, a white space character is
used. To avoid that, set the Separator property to "_"
TestSurrogateToPolarionTestLinkTy This property sets the type of link created between
pe Simulink Test Cases and the original Test Case in
Polarion. If it is set, then surrogates are created for
Test Cases when Simulink Test Cases are imported from
Polarion. If the value is empty, then links are not created
between Test Cases.
HyperlinkRoles The definition of mappings between Polarion Work Item
Types and the corresponding Hyperlink types to the
model to be created.
DefaultHyperlinkRole If HyperlinkRoles doesn't define the mapping for the
Work Item Type (see HyperlinkRoles above), this
hyperlink type is used.
QueryItemsLimit The maximum number of items to be queried in one
request to the server. (0 for no limit.) This doesn't affect
querying from LiveDocs.
TotalItemsLimitPerReqSet The upper limit for the number of items loaded into a
single ReqSet from Polarion.
Note
This is not an exact number and is calculated after the
execution of a query. (The total amount will be near
but not the actual specified value.)
Property Description
(Otherwise, an icon with text appears.)
EnableCreateNewWithRequirements Enable the Create New button in Simulink Requirements
mode. (The button appears in the Update Backlinks
drop-down list.)
LogFileName If LogFileName is not empty, logging is enabled and
creates a <LogFileName><timestamp> file in the
root folder of the Connector for each new session in
MATLAB.
LogFileRotationAfter If logging is enabled, this property defines how many log
files are created before the oldest ones are deleted.
checkUpdateURL
This URL is opened, when users click Check
Updates.
ProcessModelReferences Enables recursive processing of referenced models in
Update Backlinks.
e.g. slreq.Requirement
<class name>
Property Description
e.g. Requirement
e.g. sltest.test.manager.*
e.g. sltest.*
GeneratePictureForContext If picture export is allowed (see SurrogateContent
options), generate a picture highlighting the block in its
parent context.
ContextHighlightColor This color will be used for highlighting a block within its
parent diagram context.
Note
Highlighting is only applicable for Simulink models.
Property Description
EnableSurrogateDeletion During the Clean up Operation, if a surrogate object
is identified as an orphan (the corresponding original
model object no longer exists), the surrogate will be
marked for deletion.
Note
Programmatic zooming is only possible from R2022a+.
Use keyboard shortcuts on earlier versions.
ConnectorDefaultZoom Initial Font Size for the Connector panel. (Changing this
property, virtually applies the zoom factor.)
Tip
Refer to the Configuration.m file in the Connector installation for more information on each of these
properties.
Procedure
1. In the MATLAB editor's file explorer, navigate to the directory that you installed the Connector in.
3. Click Save when you are done configuring the advanced settings.
After changing the Configuration.m file, be sure to execute the ConfigurationService.reset
command in the Simulink console window to reflect the change. (You also must close then reopen
the Polarion pane.)
This operating mode takes advantage of the capabilities of both Requirements Toolbox and Simulink Test
Manager.
Requirements Toolbox:
You can import Requirements from Polarion into Simulink. You can then link blocks in a Simulink model to
Requirements and other artifacts managed in Polarion, with two-way navigation via the Simulink working
environment. Model blocks linked to Requirements can be published to Polarion as Surrogates which are
automatically linked to the original Requirements.
You can import Test Cases from Polarion to Simulink. You can also define Test Cases directly in Simulink
Test Manager and use them in Polarion. In each case, you can link the Test Cases to the Requirements.
You can also publish Simulink Test Cases and their associated Test Results to Polarion. Both original
Polarion Test Cases and Test Cases authored directly in Simulink Test are published to Polarion as
Surrogates Test Cases. The integration also ensures that Test Cases are linked back to the original
Requirements automatically. For Test Cases that have been executed in Simulink, Test Results can be
published to Polarion in the form of a Test Runs and Test records.
General commands:
Settings
Configure or update Polarion servers, select what Polarion projects users import from and configure
additional advanced settings.
Status
Displays the current server connection status.
This section describes how to select the context in Polarion that you want to work with in your current
Simulink model, and how to refresh the list of Polarion resources available to you.
The context can be a Polarion project, or a LiveDoc document – a requirements specification, for example.
The procedure is the same for both the Requirements Toolbox and Simulink Test and Direct Linking
modes.
Assumptions
• You have configured the Polarion server(s) and selected the Polarion project(s) you want to work
with in the Connector.
• You can log on to the connected server(s), and your user account has all permissions necessary to view,
create, and update Work Items in each project you need to interact with via the Connector.
Procedure
1. Make sure you are working in the operational mode you want to use. If not, switch to it in the
Polarion pane.
3. If you want to work in the scope of a project, with access to all its Work Items, select a project
name in the dialog box.
4. If you want to work in the scope of a LiveDoc (accessing only the Work Items it contains), expand
the node of the Space containing it, and select the LiveDoc you want.
5. After selecting the desired context, click Open.
Note
Polarion LiveDocs can be selected, viewed, and edited in the Polarion pane.
Reload List
If you added a Polarion server after the initial Connector configuration, or added, for example, a new
LiveDoc to your Polarion project, you must reload the list before it appears in the Polarion Context
Selector.
Procedure
1. Click Select Polarion Context to open the Polarion Context Selector dialog box.
2. In the dialog box, click Reload List.
A connection is established with Polarion based on the Server settings and all configured servers and
projects are scanned for new and updated artifacts.
When the process is complete, any newly added Polarion servers appear and remain on the list. If
Spaces (containing LiveDocs) or new LiveDocs were added in the defined projects, they are
also added to the list.
3. If you want to select a context at this time, you can do it now. Select it as previously described and
click the Open button.
If you don't want to select a context, you can click the Cancel button. The refreshed list is preserved.
Requirement Toolbox
The following commands are applicable when working with the Requirements Toolbox:
Import to Simulink
Import a LiveDoc containing Requirement type Work Items or import all,or a filtered group of Work
Items by importing via the project context.
Update Backlinks
◦ Update Backlinks: Process backlinks, surrogate Simulink items, block properties, and diagrams in
Polarion.
◦ Clean up Polarion: Deletes surrogate Simulink items (if used), outgoing links from those surrogate
Simulink items, and outgoing hyperlinks.
Open in Polarion
Open imported Simulink requirements and edit them directly in Polarion within Simulink.
Retrieves Polarion updates for a single Polarion artifact or all artifacts imported from the project
context. (There's no need to reimport them.)
Import to Simulink
You can either import and work with Polarion LiveDocs in Simulink or work at the Polarion project
level to filter and select the Requirement Work Items you want to import via the tracker view. You can
even import both contexts and have multiple Requirement Sets in the Requirements View.
Note
You can change the default mappings when importing Polarion Work Items (Requirements and other
Work Item types) to Simulink Requirements. Simulink Requirements offers three types that you can map
to specific Polarion Work Items: Container, Informational and Functional.
By default:
See the Advanced configuration options section to change the default mappings.
Procedure
1. Click Polarion on the top right if the Polarion pane is not already open.
2. Click Switch to Simulink Requirements mode if you are not already there.
4. Expand the project then Space containing the LiveDoc you want to import.
Tip
If you want to import an earlier revision or baseline of a LiveDoc to Simulink, use Open in
Polarion, select the target revision or document baseline, then click Import to Simulink.
6. Enter your Polarion Username and Password and click Log in.
The LiveDoc is loaded into the Polarion pane.
(Click Open Requirements View in the Polarion pane if you do not see it below your model.)
9. Right-click on the imported item and select Expand All to view all the imported Requirements.
10. The * beside the Requirement Set's name means is not saved to the local system.
Tip
If you want the outline numbers to match up, do not add a title to the LiveDoc.
If you add a title it adds an additional level to the imported outline numbers.
(The title will be 1.0.)
Note
When working with Polarion LiveDocs as the selected context, their hierarchy is always respected and
imported into Simulink. Even if you view a LiveDoc as a flat table or tree structure and adjust a query,
the original structure and hierarchy of the LiveDoc are imported. Additionally, applying filters to the
LiveDoc are ignored by the Connector, and the entire LiveDoc is still imported.
If you're looking to import Requirements from multiple LiveDocs or filter them with a query, you can
import them into Simulink from the Polarion project context.
Procedure
1. Click Polarion on the top right if the Polarion pane is not already open.
2. Click Switch to Simulink Requirements mode if you are not already there.
5. Click Open.
Polarion's tracker view loads in the Polarion pane.
Warning
• When working in the project context, check how many Work Items are listed in the Table view.
• All the found items (354 Work Items in the example above), will be imported into Simuilink. You
may or may not want to import all of them.
If the found items include some that you don't want to import, define additional queries to
refine the number of Work Items to import.
Note
If you want the items to retain the same hierarchy they have in Polarion, click Tree view.
If you keep it on Table view, the items are imported "flat" - with no hierarchical structure.
6. Click Import to Simulink to import all Work Items within the project, or filter the results.
7. (Optional) Filter the Work Items to import.
a. Click .
A list of query options appears.
Tip
Enter your own Lucene queries in the text field or search the presets.
(See the Construct queries graphically and Advanced querying sections in Polarion's Help on
Support Center for details.)
b. Select a preset or enter your own Lucene query.
The available Work Items are filtered based on your selection or query.
Polarion offers a vast and powerful set of rich text capabilities. For example, Work Item Descriptions can
contain references to other Work Items, formulas, images, different fonts, diagrams, tables, and structured
lists. Unfortunately, Simulink is somewhat limited here.
The following items are either not displayed or shown in a limited fashion in the Simulink
description field:
Referencing Work Items in description body Shown, but hyperlinks may not open in a manner that is
desirable.
Formula Not shown, but a mathematical formula reference marker
appears in the text body.
Work Item fields and custom fields Shown as custom attributes in Simulink, but the mapping
must be set up in the Configuration.m file.
Tip
• You can easily navigate back to Polarion from the imported requirement using Open in Polarion.
This allows you to see the item in Polarion in full without any restriction.
• To show Polarion custom fields as Simulink Custom Attributes, you must define the mapping in the
Configuration.m file!
Polarion Requirements imported into Simulink can be viewed and managed in the Requirements View.
Procedure
Tip
To expand the requirement Set, right-click on the imported item and select Expand All.
3. You now have a variety ways you can work with the requirement.
• Open Simulink’s Property Inspector to view basic information imported with the requirement,
such as the Summary (title), the long Description, Revision information and the Revision
number under Custom Attributes.
Tip
You can also work with Polarion revisions and Document baselines.
• Click Open in Polarion to launch the Polarion pane and view the requirement in Polarion without
leaving Simulink.
◦ If it resides in a Polarion LiveDoc, the LiveDoc opens in the Polarion pane with the Requirement
Work Item highlighted.
◦ If it comes from the project context then the Requirement Work Item opens in the Work
Item detail view.
Open in Polarion
After you import requirements from a Polarion project or LiveDoc document, you can quickly open and
view them in Polarion without leaving Simulink.
Procedure
Procedure
Results
If you are working with Polarion in the context of a LiveDoc document, that document opens in the
Polarion pane, and the Work Item corresponding to the selected requirement is selected in the document.
If you are working with Polarion in the context of a project, the tracker view of Work Items opens in
the Polarion pane, and the Work Item corresponding to the selected requirement appears there.
You can also work with Polarion revisions, Document baselines, and Documents branched with referenced
Work Items . The process works essentially the same as when working with Head revisions.
Note
When working with Polarion Document revisions, the Import1 line item in the ReqSet summary field
displays the revision number of the Polarion Document you imported. You can obviously navigate back
to it from Simulink to Polarion by clicking Open in Polarion.
Work Item revision information is stored in the Simulink requirements rev custom attribute.
You can display this attribute in the Simulink Requirements table view.
You can view the revision history of any Polarion LiveDoc or Work Item while working inside Simulink
requirements.
Procedure
1. Select the requirement that you want to view the history of in the Requirements View.
2. If the Polarion pane is not already open, click Polarion on the top right.
• Select Requirement Set or Import1 in the Requirements View then click Open in
Polarion History to view the history of the LiveDoc at the correct revision.
• Select Requirement Set or Import1 in the Requirements View and click Open in
Polarion to open the LiveDoc.
You cannot view the entire history of a project but you can view the history of all the LiveDocs and Work
Items you imported via the project context.
Procedure
1. Select the requirement you want to view the history for in Requirements View and click Open
in Polarion History.
The selected item's history appears on the Polarion pane.
2. If you select the top level elements ( Requirement Set or Import1 ) of a project, you receive
the following warning:
Refresh/Refresh All
Once you have imported one or more Polarion artifacts to Simulink, you may need to update them later.
Regardless of the working context (project or Document), you can quickly update the content in Simulink.
You can choose to refresh one or more ReqSets.
Note
It doesn’t matter what is currently in view in the Polarion pane when carrying out this action.
Each time the ReqSet is refreshed or updated with new information, you see a highlight of what was
updated in the Comments field of the Import1 line item.
Refresh
Procedure
Note
It doesn’t matter what is currently in view in the Polarion pane when carrying out this action.
Refresh All
Procedure
Re-import
Sometimes you need to re-import Polarion artifacts into Simulink. (Like when a Polarion configuration
changes.)
Note
If the configuration changes (like switching to the baseline of a Document), the Connector attempts
to preserve traceability. (Links from the model to the requirements go to the updated version of the
Document.)
Procedure
1. You are working with a Baseline of a Polarion LiveDoc, and you wish to replace the current ReqSet
that represents the Baseline with a newer one.
2. You are working in the project context, and you decide that you not only want to import System
requirements, but also Software requirements, and have them all be part of the same ReqSet.
In these cases, you can choose to update the configuration of the ReqSet to reflect these situations. The
process is similar to importing the Polarion artifacts for the first time. First, you bring the context up in the
Polarion pane with the appropriate document revision or project-scope query, and then you re-import.
The connector informs you that a ReqSet already exists, and you have three options:
Procedure
If you are working in the Project context, and you remove any artifacts that were linked to model elements,
then when you re-import, these links will obviously no longer be valid. Even if you decide to bring back
these artifacts later to the same ReqSet, those links will still no longer be valid. This is because Simulink
assigns a unique identifier each time the ReqSet artifacts are created. So, the identifier would no longer be
the same on a new import operation.
Procedure
1. Ensure that you have a LiveDoc or project-scope view in the Polarion pane. Then, apply either a
LiveDoc baseline/revision or a new project-scope query. (If it's a LiveDoc within a Collection, the
Collection defines its version and revision.)
2. Click Import.
The integration will check to see if the ReqSet already exists.
If the connector does not find that there is a configuration change, it will prompt you to refresh the
ReqSet. This is the equivalent of simply refreshing, as discussed earlier.
If the connector finds there is a configuration change, you can either overwrite the existing ReqSet or
create a new ReqSet based on the new configuration. If you are working with Documents (either in the
Head or a revision/baseline), you are only able to replace an existing ReqSet or Cancel. You cannot have
another ReqSet representing a different revision or baseline of the same Document already imported as a
ReqSet.
Tip
Recommendation: If you replace an existing ReqSet with an older or newer Document revision where
links existed, we highly recommend that you run Update backlinks to ensure that Polarion links
point to the correct revisions.
Update Backlinks
Depending on if you are using Simulink surrogates or not, it is possible to update Polarion with information
concerning links from Simulink model elements to requirements. If surrogate mode is enabled, the
integration creates surrogate model elements inside Polarion (with block properties, and when applicable,
the Simulink diagram) and links those elements to original requirements.
If surrogate mode is not enabled, the integration creates a hyperlink from the original requirement to the
model element and a block properties table inside of Polarion. The original requirement is also updated
with (when applicable) the Simulink diagram.
See the Linking Schema section for a visual representation of the linking.
To update Polarion with link information and to create surrogate elements (if enabled), use:
Procedure
• Surrogate Simulink elements are created for any Simulink block linked to a requirement that originated
from Polarion.
• The surrogate Simulink element contains block properties and the Simulink diagram when applicable.
The Simulink diagram can contain a single "context" diagram if a base model element is linked. When
the model element is a sub-system, the sub-system's contents appear in a diagram, as well as the
context diagram the sub-system is a part of.
The block properties appear in a table in the Work Item (surrogate) description.
Tip
You can configure how this information is displayed and ordered in the Work Item in the
Configuration.m file.
• A hyperlink is created that navigates from the surrogate Simulink element back to the Simulink block.
• Outgoing links are created from the surrogate Simulink element to original linked Work Items
(requirements).
Note
The surrogate Simulink element will link back to the revision when requirement revisions or baselined
Documents are used.
• The Polarion requirement is updated, and when applicable, the Description is updated with the
Simulink diagram and the properties table.
• A hyperlink that navigates back to the Simulink block is created.
If you choose to use multiple Polarion projects with one Simulink model, the integration creates for each
Simulink block a surrogate Simulink block for each Polarion project.
Example
Model X is used with two Polarion projects: Polarion project A and Polarion B.
After linking the Block Integration to Polarion requirements in both Polarion Project A and B, after backlink
processing, Simulink surrogate item will exist in Polarion project A and B.
Updates to Polarion
Click Update Backlinks (again) to update information if you update Simulink diagrams, block
properties, or change incoming links.
Once the Polarion pane refreshes, the updates have been correctly processed in Polarion.
Clean up Polarion
If you delete model elements that are linked to requirements inside of Simulink, or just delete a link from a
model element to a requirement, you should run the Clean up Polarion action.
Procedure
1. Click the down arrow next to Update Backlinks and select Clean up Polarion.
2. The Clean up Polarion process launches. The integration will analyze the model and Polarion and
present you with a link cleanup table.
What to do next
For all configured Polarion projects and instances, the Connector will delete:
Note
Only surrogates that are associated with the current model are considered. (The Connector not delete
surrogates from projects where the source of the surrogates comes from other models.)
• Any Polarion artifact other than Simulink surrogate elements (see above).
• Polarion requirement Description fields that were linked to Simulink blocks, where the Description field
was updated with a Simulink diagram. These requirements get linked with Simulink blocks without the
use of surrogates. (The original requirements are updated.)
Both Update backlinks and Clean up Polarion ensure that Polarion accurately represents the
current state of the model. They should be used together to ensure that Polarion is always up to date.
You can work with Polarion Revisions or Document baselines in both Requirements Toolbox and
Simulink Test and Direct Linking modes.
In Requirements Toolbox and Simulink Test mode, open the target Polarion Document baseline or
revision in the Polarion Pane, then import it.
Note
If you are working with revisions but are not using surrogates, you cannot update a Polarion Work Item
revision with backlinks to Simulink.
If you open a historical version of a requirement, you do not see a surrogate linked to it, but a link to the
surrogate is visible in the requirement's head revision.
(Following the link from the head revision takes you to it.)
The correct link is only visible from the surrogate and only in a single direction.
If you delete the original requirements or Work Items in Polarion, they are also deleted in Simulink when
the Refresh or Refresh all actions are run.
Note
• The links from these Polarion artifacts to Simulink model elements remain and should be regularly
cleaned in both Simulink and Polarion.
• To automatically clean up links and remove surrogates, use Cleanup Polarion.
(You must manually remove invalid links in Simulink.)
Suspect Flags
When requirements or Work Items are changed in Polarion and updated in Simulink, any updated
requirements linked to model elements are flagged as Suspect. Use Clear change issues in Simulink
Requirements to clear out these Suspect requirements. See the Requirements Toolbox documentation
for more information.
Note
From Simulink 2022b onwards, tracking changes to requirement links is off by default and must be
enabled if you wish to detect changes to imported Polarion Requirements. Please see Track Changes to
Requirements Links in Simulink's requirements documentation for more information on how to enable
change tracking.
Similarly, if Simulink items linked to Polarion Requirements are changed, then after backlinks are
updated (and if MarkSurrogateSuspectOnChange is set to "true"), the outgoing link is marked
as Suspect.
When using Requirements Toolbox and Simulink Test mode, after Polarion Work Items or requirements
have been imported into Simulink and links are created to Simulink items, users can show the coverage of
these requirements with Simulink Requirements' Implementation status feature. See the Requirements
Toolbox documentation for more information.
You can also view coverage information in Polarion, but we recommend that you work with surrogates to
easily display this information. Once backlinks have been processed with surrogate Simulink items, you can
create LiveReports using the Requirement traceability widget with the original Polarion Work Items
linked to surrogate Simulink item work items.
You can also import content from the Polarion Collections into Simulink.
Note
If you previously imported a Document that is now part of a Polarion Collection:
When you import the Collection, you are notified that some Documents will be translated from their
standalone copies to the version in the Collection.
Procedure
1. Select the Collection you want to work with. You can do it two ways:
OR
iii. Click the Collection's name in the bottom pane to open it.
2. Check the Documents to confirm that they are what you want to import into Simulink.
Note
Each Document is imported to Simulink as a separate ReqSet.
Results
When you open the imported Documents or Work Items by clicking Open in Polarion, they open in the
Collection context.
It's important to note that when working with Simulink surrogate items and Collections, although the
integration establishes outgoing links from the surrogate items to the original Polarion requirements, these
links will not be visible from the requirement side if the requirement was either a revision (baseline) or
at the head. This is because when working in the Collection context, Polarion will not show links that go
outside the Collection context by default.
To see links from the requirements side back to the surrogate items:
To see links from the requirements side back to the surrogate items, you must move the Simulink surrogate
items into a Document manually and then add this to the Collection you imported from. Only then will
these backlinks become visible within the Collection for either head revisions or baselines.
Note
• By default, the Connector will automatically skip Documents containing Simulink surrogate items, so
we recommend not mixing Simulink surrogate items and regular Work Items in the same Document.
You can configure this setting in the Configuration.m file.
• This means that any Simulink surrogate Work Items moved into a Collection that is then refreshed
or re-imported into Simulink are ignored during that refresh or import.
Procedure
2. Select the Work Item type you use for Simulink surrogates. ( Simulink Item by default.)
Note
Polarion makes it easy to move Work Items into Documents.
3. Select the Simulink surrogate Work Items you want to move into a Document and select Move.
5. Move this Document into the Collection you used for the import into Simulink.
Note
Make sure you add the head revision of this Document into the Collection because if you make
changes to these Simulink surrogate Work Items during further backlink processing, you will want
these changes reflected in the Document (and associated Collection).
Now, when you view the linked Polarion requirements inside the Collection context, they show
the correct links in both directions.
Results
Here, you can see a Polarion requirement imported to Simulink. A model element linked to that
requirement and backlink processing has resulted in a surrogate Work Item representing the linked model
element created in Polarion.
When viewing the requirements in the Collection context, we can now see the backlink to the
surrogate model element.
The Simulink Requirements infrastructure supports the linking of different artifacts with Polarion
Requirements.
Tip
• Links should be “incoming” for Polarion Requirements. For example, when linking a Simulink/Polarion
Requirement, you can create the link in both directions, but backlink processing is triggered in
Polarion only if the link is incoming. If it is the opposite direction, then Simulink Requirements
processes backlinks, and no Polarion-specific functionality is triggered.
• See Simlulink's documentation for more information on how it handles forward links.
When you Update Backlinks from the Connector panel, the integration creates surrogate Work Items
for the modeling items (Data-dictionary or Simulink Requirements, for example) in Polarion.
The type of Work Item created for these items is determined by the ExtendedSurrogateItemType
property in the Configuration.m file.
(See the Advanced configuration options section or the Configuration.m file itself for more information.)
Note
• The Connector was tested for the traceability of Simulink Model Blocks, Stateflow, System Composer
models, data-dictionary entries, Simulink Requirements, Justifications, System Composer Sequence
Diagram, MATLAB code and Simulink Tests.
• You can only link MATLAB code to a Polarion Requirement if you are using MATLAB R2022b or newer.
• Other MATLAB toolboxes may or may not work correctly.
• Please contact us if some links are not reflected in Polarion or cause processing errors.
In Simulink, you can define the types of links between MATLAB artifacts and Requirements.
Properties, under the Property Inspector displays the default link types between System Composer
objects and Requirements.
When processing backlinks, you can set link roles on the Polarion side to map those from MATLAB with the
SurrogateLinkMapping property in the Configruation.m file.
MATLAB R2023 introduced a new feature called Sequence Diagrams, and a big request from their
customers is traceability between requirements and Sequence Diagram elements
Even though MATLAB's API for this feature is not yet available, Polarion and MathWorks partnered and are
happy to announce the beginning of this realization.
With our Connector version 3.3.0 you can now link Polarion requirements to the Type and Name of
Sequence Diagram elements.
Information like user IDs, passwords, and personal access tokens (PATs) were previously stored in the local
MATLAB preferences as plain text. They are now encrypted.
Note
If you downgrade to a Connector version older than 3.3.0, you must reenter your credentials because
older versions will not know how to decrypt them.
Simulink Test
The following commands are applicable when working with Simulink Test:
• With this button, you can import all Work Items of the chosen context (LiveDoc or Project) into
Simulink Test while respecting the original hierarchy.
• If a filter is applied when working in the Project context, only the queried Work Items are imported.
If there are links between Test Cases and Requirements that were already imported into Simulink,
corresponding links are created in the Requirements Toolbox when the Test Cases are created in
Simulink Test.
• See the data model diagrams for Simulink Test.
Example
By default, the heading Work Items are mapped to Test Suites in Simulink Test.
If you use multiple Work Item types in the LiveDoc or within the Project-level query, or if you filter the
Work Items, you may want to automatically ignore them during import.
Open TestRuns
This button launches the Test Run view in Polarion and preselects Test Runs related to Simulink Test.
Execute TestCases
This button triggers the execution of any Test Cases in Simulink Test linked to Polarion Requirements. It
also collects the Test Case results in Polarion as Test Records. They are visible in the Surrogate Polarion
Test Case Work Item, which displays the Test Run and associated Test Results.
This button publishes to Polarion the Test Results of any previously executed Simulink Test Test Cases
linked to Polarion Requirements. Their Test Records are visible in the surrogate Polarion Test Case Work
Item, which displays the Test Run and associated Test Results.
Update Backlinks
This button processes and creates Test Case Surrogates and backlinks for any Test Case that is linked to
an original Polarion Requirement (or other Work Item). The Test Case might have originated in Polarion
and imported or authored directly in Simulink Test.
Note
When Test Cases are executed, a new Test Run is created in Polarion. PolarionThe Test Run's layout is
based on a template, and users can specify the ID of that template in the Configuration.m file.
%
% Test Run Template - New Test Runs from Simulink are created on
top of this template.
%
TestRunTemplate = ‘Simulink Tests’;
• Create a template with the name specified by TestRunTemplate in the Configuration.m file. This
template has to be defined in the project or projects that are used by the Connector.
• Change the Configuration.m file to point to an already existing template.
You can either import and work with Polarion LiveDocs in Simulink Test or work at the Polarion
project level to filter and select the Test Case Work Items you want to import via Polarion's tracker view.
You can even import both contexts and have multiple Test Files in Simulink Test.
Procedure
1. Click Polarion on the top right if the Polarion pane is not already open.
2. Click Switch to Requirements Toolbox and Simulink Test mode if you are not already there.
4. Expand the project then Space containing the LiveDoc you want to import.
Tip
If you want to import an earlier revision or baseline of a LiveDoc to Simulink:
(Only a single revision/basline or head revision of a LiveDoc can exist as a TestFile within Simulink
Test Manager.
6. Enter your Polarion Username and Password and click Log in.
The LiveDoc is loaded into the Polarion pane.
When complete, the new Simulink Test file appears in Simulink Test Manager. You are now free to
further refine these Test Cases inside Simulink Test.
Note
• When working with Polarion LiveDocs as the selected context, their hierarchy is always respected
and imported into Simulink Test. The heading Polarion LiveDoc items are mapped to Test Suites in
Simulink Test.
• Even if you view a LiveDoc as a flat table or tree structure and adjust a query, the original structure
and hierarchy of the LiveDoc are imported.
• Applying filters to the LiveDoc are ignored by the Connector, and the entire LiveDoc is still imported.
• If you prefer importing Polarion Test Cases as a flat list ignoring the heading structure in the LiveDoc,
you can modify the IgnoreImportTestCasesForTypes parameter in the Configuration.m file.
• You can also change the behavior and allow headings to be imported as Test Cases rather than Test
Suites with the ConvertHeadingsToTestSuites property in the Configuration.m file.
If you want to import Test Cases from multiple Polarion LiveDocs or you want to filter them with a
query, you can import them into Simulink Test from the Polarion project level.
Procedure
1. Click Polarion on the top right if the Polarion pane is not already open.
2. Click Switch to Requirements Toolbox and Simulink Test mode if you are not already there.
Warning
• When working in the project context, check how many Work Items are listed in the Table view.
• All the found items (354 Work Items in the example above), will be imported into Simulink. You
may or may not want to import all of them.
If the found items include some that you don't want to import, define additional queries to
refine the number of Work Items to import.
If you keep it on Table view, the items are imported "flat" - with no hierarchical structure.
6. Click Import to Simulink Test to import all Work Items within the project, or to filter the results.
7. (Optional) Filter the Work Items you want to import.
a. Click .
A list of query options appears.
Tip
Enter your own Lucene queries in the text field or search the presets.
(See the Construct queries graphically and Advanced querying sections in Polarion's Help on
Support Center for details.)
b. Select a preset or enter your own Lucene query.
8. Click Import to Simulink Test. Simulink creates a new Simulink Test file with the filtered Test
Cases (or other Work Items).
You can now further refine these Test Cases in Simulink Test if you want.
Note
• If there are links between Test Cases and Polarion Requirements, and those Polarion Requirements
have been previously imported into the Simulink Requirements Toolbox, then the integration
automatically creates links from Test Cases to Requirements in Simulink.
• If you modify links after they were previously imported, then they are not removed in Simulink Test.
This is currently a limitation with Simulink Test.
• If you modify the LiveDoc and re-import it, the Connector attempts to synchronize the associated Test
Cases and the hierarchy in Simulink Test.
• Only one revision, baseline, or head revision of a LiveDoc can exist as a Test File within Simulink Test.
• Branched documents with referenced Work Items are also supported.
You can choose to author Test Cases directly in Simulink Test. You can decide to only import higher-level
Test Cases from Polarion, and then derive applicable lower-level Test Cases directly in Simulink Test
to test your model. Simulink Test offers several methods to create Test Cases from models. You can,
for example, create them automatically or via scripts. See the Simulink Test documentation for more
information.
When you import Polarion Test Cases and Requirements into Simulink Requirements Toolbox and
Simulink Test, links that existed between Test Cases (Work Items) and Requirements (LiveDocs) get
created by the Connector.
You can also manually create links between Simulink Test Cases and Requirements but that's outside the
scope of this document. See the Simulink Test documentation for more information.
Once you establish a link between Simulink Test Cases and Requirements imported from Polarion, you can
reflect these Test Cases back in Polarion.
• Surrogates are always created for Simulink Test Cases. (If they originated from Polarion or were authored
directly in Simulink Test.)
• Surrogate Test Cases get created in Polarion for any Test Case linked to a Polarion Requirement.
Tip
See Linking Schema for a visual representation of the linking.
Update Polarion with link information and create Test Case surrogate elements:
• Surrogate Test Cases are created for any Simulink Test Case linked to a Requirement that originated
from Polarion. The surrogate Test Case is created in the same Polarion project where the original
Requirement is.
• The surrogate Simulink Test Case contains information and properties about the Simulink Test Case.
• A hyperlink is created that navigates from the surrogate Simulink Test Case back to the Simulink Test
Case in Requirements Toolbox and Simulink Test mode.
• Outgoing links are created from the surrogate Simulink Test Case to the original linked Work Items
(requirements) and to the original Test Cases (if they were imported to Simulink Test previously).
Note
The surrogate Simulink Test Case links back to the revision of a Requirement and Test Case when
revisions or baselined Documents are used.
When using suspect flags, the Connector will not trigger the Polarion suspect flag on a Simulink surrogate
Work Item linked to a Polarion requirement if the context diagram for a low-level Simulink item is visually
changed. (For example, if blocks are re-arranged in the diagram). This is to avoid triggering the suspect
flag for trivial changes.
However, changing low-level parameters, properties, labels, etc. does trigger the suspect flag for the
corresponding Simulink surrogate Work Item.
If sub-system diagrams are changed in any way, this will always trigger the suspect flag.
If you change a Simulink Test Case in the following ways, the Simulink Test Surrogate is updated the next
time backlink processing is executed:
Note
If the MarkSurrogateSuspectOnChange configuration property is set to “true”:
The outgoing link to the original requirement is marked as Suspect if the Simulink Test Case is changed.
Clean up Polarion
If you delete Simulink Test Cases linked to Polarion Requirements inside of Simulink Test or delete
links from Simulink Test to imported Polarion Requirements or Work Items, you must run Clean up
Polarion.
Procedure
1. Click the down arrow next to Update Backlinks and select Clean up Polarion.
2. The Clean up Polarion process launches. The integration will analyze the model and Polarion and
present you with a link cleanup table.
What to do next
For all Polarion projects and instances, the Connector will delete:
• Any Polarion artifact other than Simulink surrogate elements (see above).
Both Update backlinks and Clean up Polarion ensure that Polarion accurately represents the
current state of the model. They should be used together to ensure that Polarion is always up to date.
The integration makes it easy to quickly execute Test Cases linked to Polarion Requirements, collect their
results, and publish them back into Polarion. If a Test fails, Polarion automatically generates a Defect
Work Item and links it back to the revision of the Surrogate Test Case, creating the Defect. The Test Case
results are stored as Test Records in a Test Run. The Test Record has a reference to the revision of the
Surrogate Test Case at its time of execution. When you execute the same Simulink Test Case multiple
times, it appears in different Test Runs in Polarion.
Execute a Test
Procedure
2. When complete, Simulink Test displays executed test results in the Results & Artifacts Tab.
3. Click Open TestRuns to open the associated Test Result dashboard in Polarion for the Simulink
Tests.
The Test Run dashboard launches in Polarion.
You can choose to execute tests directly inside of Simulink Tests. Then, after running the tests, you can ask
the Connector to gather the latest Test Results and publish them back to Polarion.
If you defined but did not execute a Test Case, Polarion still creates a Test Run for it but marks it as
waiting.
Procedure
1. Click Publish TestCase Results to Polarion to publish Test Case results to Polarion for any Test
Cases linked to an original Polarion Requirement.
Once published, Test Case results appear in the Test Run dashboard.
What to do next
This makes it easy to view Simulink Test results. (Which Test Cases passed, failed and additional result
details.)
When a Test Case fails, Polarion generates a Defect and links it back to the Test Case.
Direct Linking mode mimics the functionality of the original Polarion Connector for Simulink. If you are
familiar with that, and you do not need the newer interoperability between Simulink Requirements and
Polarion provided by Requirements Toolbox and Simulink Test, then you will most likely want to use
Direct Linking mode.
• Link a selected Block in a Simulink model to an existing Requirement (or other selected Work Item
type) in Polarion.
• Publish selected Blocks in a Simulink model to new Polarion Work Items of a type configured for the this
purpose in the target Polarion project.
• Create New: You can link to a new Work Item during the linking process.
This section describes how to select the context in Polarion that you want to work with in your current
Simulink model, and how to refresh the list of Polarion resources available to you.
The context can be a Polarion project, or a LiveDoc document – a requirements specification, for example.
The procedure is the same for both the Requirements Toolbox and Simulink Test and Direct Linking
modes.
Assumptions
• You have configured the Polarion server(s) and selected the Polarion project(s) you want to work
with in the Connector.
• You can log on to the connected server(s), and your user account has all permissions necessary to view,
create, and update Work Items in each project you need to interact with via the Connector.
Procedure
1. Make sure you are working in the operational mode you want to use. If not, switch to it in the
Polarion pane.
3. If you want to work in the scope of a project, with access to all its Work Items, select a project
name in the dialog box.
Tip
Importing from the project context uses the Polarion tracker view to select the Polarion Work
Items to bring into Simulink.
4. If you want to work in the scope of a LiveDoc (accessing only the Work Items it contains), expand
the node of the Space containing it, and select the LiveDoc you want.
5. After selecting the desired context, click Open.
Note
Polarion LiveDocs can be selected, viewed, and edited in the Polarion pane.
Reload List
If you added a Polarion server after the initial Connector configuration, or added, for example, a new
LiveDoc to your Polarion project, you must reload the list before it appears in the Polarion Context
Selector.
1. Click Select Polarion Context to open the Polarion Context Selector dialog box.
2. In the dialog box, click Reload List.
A connection is established with Polarion based on the Server settings and all configured servers and
projects are scanned for new and updated artifacts.
When the process is complete, any newly added Polarion servers appear and remain on the list. If
Spaces (containing LiveDocs) or new LiveDocs were added in the defined projects, they are
also added to the list.
3. If you want to select a context at this time, you can do it now. Select it as previously described and
click the Open button.
If you don't want to select a context, you can click the Cancel button. The refreshed list is preserved.
This topic explains how to directly link a Block in a Simulink model to an existing Work Item in Polarion
(typically a Requirement of some type) when working in the Connector's Direct Linking mode.
Note
• In order for the new connector to work in a similar way to older versions of the connector with direct
linking, the CreateSurrogatesForBacklinks option in the connector settings must be set to
false.
• If it is set to true (the default setting), after a direct link is created from a model element to a
Polarion Work Item and backlink processing has been run, surrogate Simulink Items for Simulink
blocks are created in Polarion, with outgoing links to the original Work Item in Polarion. This may or
may not be desirable to how you have worked in the past.
You should refer to the link schemas for both Direct linking and Simulink Requirements Mode, with and
without surrogates.
There are two distinct operations, which must be carried out in the following order:
Procedure
After these two steps, a two-way link is established, enabling navigation from a linked Block directly to the
corresponding linked Work Item in Polarion and vice versa.
You can use two methods to create links from Simulink blocks to Polarion Work Items (requirements). One
uses the Polarion Work Item picker; the other uses the copy link approach.
Procedure
1. In the Polarion pane, locate the Work Item you want linked to a Simulink Block and select it.
2. Copy the Work Item link to your Clipboard:
Note
It is possible to copy Work Item revisions into the copy buffer for linking. First, use the Live Document's
history or Work Item revision to find the correct revision or baseline, then copy the Work Item link to
the copy buffer using the copy link. Refer to Polarion's online Help for more information.
Procedure
1. In Simulink, select the Block you want linked to the selected Work Item in Polarion.
2. In Polarion, click Link to existing.
The Polarion Work Item picker launches.
3. Select one or more Work Item you wish to link to the Block.
4. Click Confirm to create the link.
Note
• The Picker only displays Work Items in the current working context. For example, Live Doc or the
project-scope tracker view. You can choose to override this by changing the query at the top of the
table.
• It is possible to select multiple Work Items using the Work Item picker.
You must use the Work Item picker approach to link a Simulink block to multiple Work Items
(requirements) at once.
• The Work Item picker supports Live Doc revisions. If a Live Doc Baseline or revision is the current
working context and the Work Item picker is launched, all Work Items shown are revisions.
In Simulink, you can anchor a requirement link to the Diagram Canvas, but in Direct Linking mode, you
cannot select the Canvas to create a link to Polarion. Instead, use the Simulink requirements context
menu.
1. Open the Simulink diagram you wish to create the top-level link from.
2. In Polarion, copy the Work Item link into the copy buffer.
(See the notes above on using the copy buffer method to create links).
3. Move the mouse over the diagram canvas and right-click to open the Simulink context menu.
Note
• If you use System Composer, select the Requirements menu item.
• Another option is to use an Area block to anchor a requirement. Then you can use the methods of
establishing a link already described in this section, including the Work Item picker.
You can optionally direct-link a model Block in Simulink to a new Work Item in Polarion that you create via
the linking process. You might do this if you discover that something in a model Block should have a new
Requirement in Polarion, or perhaps you discover an issue with something in the Block, and want to track it
with an Issue in Polarion.
Caution
To create the direct linking described here, the CreateSurrogatesForBacklinks option in the
Connector settings must be set to false.
If it is set to true (the default setting), linking creates surrogate Simulink Items inside of Polarion, and
then links from them to the original Work Item in Polarion.
Procedure
1. In Simulink select the Block that you want to direct-link to a new Work Item in Polarion.
Optionally edit other fields of the Work Item as needed. For example, you might change the Severity,
Priority, Categories, or Assignee(s) fields.
5. Save the new Work Item in Polarion.
What to do next
Note
• At this point the connection is unidirectional. Simulink knows there is a linked resource in Polarion,
but Polarion doesn't know about the linked resource in Simulink. To make the linking bidirectional,
you must update backlinks.
• You cannot create a link from the Diagram Canvas to a new Work Item in a single step. Instead, you
must first create a new Work Item in Polarion, then link it using the method described in the Link
from a Simulink Diagram Canvas to an existing Polarion Work Item section.
Update Backlinks
Depending on whether or not you are using Simulink surrogates, it is possible to update Polarion
with information concerning links from Simulink model elements to requirements. If surrogate mode is
enabled, the Connector creates surrogate model elements inside Polarion (with block properties and,
when applicable, the Simulink diagram) and links those elements to original requirements.
If surrogate mode is not enabled, the Connector creates a hyperlink from the original requirement to the
model element. The original requirement is also updated, when applicable, with the Simulink diagram.
To update Polarion with link information and create surrogate elements (if enabled), click Update
Backlinks. The backlinking process launches. When the Polarion browser refreshes, the backlinking process
is complete.
• Surrogate Simulink elements are created for any Simulink block linked to a requirement that originated
from Polarion.
• The surrogate Simulink element contains block properties and the Simulink diagram when applicable.
The Simulink diagram can contain a single "context" diagram if a base model element is linked. When
the model element is a sub-system, the sub-system's contents appear in a diagram, as well as the
context diagram the sub-system is a part of.
The block properties appear in a table in the Work Item (surrogate) description.
Tip
You can configure how this information is displayed and ordered in the Work Item in the
Configuration.m file.
• A hyperlink is created that navigates from the surrogate Simulink element back to the Simulink block.
• Outgoing links are created from the surrogate Simulink element to original linked Work Items
(requirements).
Note
The surrogate Simulink element will link back to the revision when requirement revisions or baselined
Documents are used.
• The Polarion requirement is updated, and when applicable, the Description is updated with the
Simulink diagram and the properties table.
• A hyperlink is created that navigates back to the Simulink block.
Note
• If Simulink blocks are linked to Polarion revisions or Baselines, the corresponding requirement will not
be updated in Polarion. This is because Polarion does not allow historical revisions of artifacts to be
updated.
• Typically, a Simulink model is used with one Polarion project, so the integration creates a
corresponding Surrogate Simulink block for each Simulink block.
If you choose to use multiple Polarion projects with one Simulink model, the integration creates, for each
Simulink block, a surrogate Simulink block for each Polarion project.
Example
Model X is used with two Polarion projects: Polarion project A and Polarion B.
After linking the Block Integration to Polarion requirements in both Polarion Project A and B, after backlink
processing, Simulink surrogate items will exist in Polarion project A and B.
Updates to Polarion
Click Update Backlinks (again) to update information if you update Simulink diagrams, block
properties, or change incoming links.
Once the Polarion pane refreshes, the updates have been correctly processed in Polarion.
Clean up Polarion
If you delete model elements that are linked to requirements inside of Simulink, or just delete a link from a
model element to a requirement, you should run the Clean up Polarion action.
Procedure
1. Click the down arrow next to Update Backlinks and select Clean up Polarion.
2. The Clean up Polarion process launches. The Connector analyzes the model and Polarion and
presents you with a link cleanup table.
What to do next
For all Polarion projects and instances, the Connector will delete:
• Any Polarion artifact other than Simulink surrogate elements (see above).
• Polarion requirement Description fields that were linked to Simulink blocks, where the Description field
was updated with a Simulink diagram.
Both Update backlinks and Clean up Polarion ensure that Polarion accurately represents the
current state of the model. They should be used together to ensure that Polarion is always up to date.
The Publish feature is the base functionality of the original version of the Connector. You can use it
to publish elements of a Simulink model to Polarion. The process creates a new Work Item in Polarion for
each model element published, and a link from each model element to the respective new Work Item.
This is the most basic form of connectivity between Simulink and Polarion. Here are some points to keep in
mind:
• The type of the target Work Item is configurable in Polarion projects. Before publishing, be sure that an
appropriate type exists in the Polarion project configuration. (Simulink Item is a commonly used type
name.)
• A Work Item created in Polarion by the Publish feature is not linked to anything. The only link is from
the element in Simulink to the Work Item. Any other links must be created manually.
Publish to Polarion
Procedure
3. In the Polarion pane, click Select Polarion Context, and in the dialog box select the project in
which you want to publish your Simulink model elements.
4. In your Simulink model, select the element(s) you want to publish to Polarion.
7. In the Polarion pane, click Update Backlinks and wait for the system to process backlinks from
the new Work Item(s).
The process creates a hyperlink in each Work Item leading to the corresponding model element in
Simulink, thereby establishing bidirectional navigation.
You can easily open the linked Polarion Work Item previously direct-linked from a Simulink Block. You can
open the latest (Head) revision of the linked Work Item in Polarion, or any revision in its History, including
Baselines.
Procedure
Procedure
1. In Simulink, select the model Block you want to open in Polarion History.
Linking schema
Debug mode
Debug mode is automatically enabled in Beta releases. Production releases have this option switched off.
If you experience any issues and would like to report them to Siemens, please enable Debug, reproduce
the problem and send the log files along with your report.
Debug mode displays what is happening while using the Connector in Matlab's Command Window.
Log files are also created in the Connector installation folder. If you encounter issues with the Connector,
send the log file created when the incident occurred to Siemens support or attach it to any incident report
you file.
1. To disable Debug mode, edit the Configuration.m file and set the Debug parameter to false.
The Connector can sometimes determine after the fact that an operation you did failed.
When it does, it temporarily enables Debug mode (switches Debug=true in the Configuration.mfile) and
prompts you to repeat the operation so that it can gather vital data to send to the development team.
It creates a ConnectorDiagnostics.zip file containing the diagnostic data in the following directory:
/Users/[USER NAME]/SVN/Simulink/ConnectorDiagnostics.zip
Tip
You can also click Collect Diagnostic on the Connection Properties dialog under Settings to
temporarily enable Debug mode and create a ConnectorDiagnostics.zip file.
This version of the Polarion Connector for Simulink comes with an uninstaller file.
Click on the uninstall.p file in the Connector's installation directory to completely remove it from your
system.
Acknowledgments
• MathWorks , MATLAB , and Simulink are registered trademarks of The MathWorks, Inc. in the United
States and other countries.
• Steve Hoelzer. progressbar, MATLAB Central File Exchange.
Copyright (c) 2005, Steve Hoelzer All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided
that the following conditions are met: * Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer. * Redistributions in binary form must
reproduce the above copyright notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
• Polarion and Polarion ALM are registered trademarks of Polarion AG, a Siemens Digital Industries
Software company.
Note
• The Microsoft Team Foundation (TFS) Connector requires an additional license.
• The Azure DevOps services have new URLs (https://dev.azure.com/[organization]), but
they continue to support old URLs, too (https://[organization].visualstudio.com).To
connect to the Azure DevOps services (TFS cloud), continue using the old URLs. Since Azure DevOps
services do not have any project collections under organization, use the DefaultCollection
value for the collection when creating synchronization pairs. For more information about
TFS URLs, see https://learn.microsoft.com/en-us/azure/devops/release-notes/2018/sep-10-azure-
devops-launch#administration.
Limitations
• The file name of an image must not contain the ampersand (&), backtick (`), tilde (~), or hash sign (#)
characters when inserting an image into a TFS rich text field.
• An image inserted into a TFS rich text field must have a different name than any existing Work Item
attachments.
• If attachments have identical file names, only the attachment that was added first will be synced.
• Naming an attachment image.png may cause issues if multiple images are copied and pasted into a TFS
rich text field.
• Currently, Polarion does not support syncing of Emojis and Code-styled text from or to TFS rich text
fields.
• Text that is styled as underlined and strike-through in rich text fields is not supported. In a uni-directional
sync, this kind of text will cause the synchronization to always show a change. In a bi-directional sync,
the underline and strike-through style will be removed from the text in the second sync.
• TFS 2018: In certain cases, newlines in rich text fields of TFS 2018 items will not be displayed in
Polarion. Please re-add the newlines in Polarion and run the sync again.
• Currently, Polarion does not support the syncing of equations in rich text fields to TFS.
• Syncing of comments is not supported.
• Currently, synchronizing multi-valued fields to and from TFS is not supported.
Warning
If a TFS project is renamed, the connection database must be updated to prevent the creation of
duplicates.
The TFS connector has a single connection database per Connection, Collection and Project Name tuple/
combination.
Connection settings
To connect to a TFS server, you need the URL of the server and a personal access token.
Note
• You cannot use Password authentication because the REST API for TFS/ Azure DevOps does not
support it.
• When connecting to a TFS 2018 instance as a user without the Edit instance-level
information permission, where DefaultCollection is not configured, you must use
the com.siemens.polarion.tfsconnector.connectionCheckCollections configuration
property.
• If you do not have the Bypass rules on work item updates permission, please set
the com.siemens.polarion.tfsconnector.bypassrules.enabledsystem configuration
property to false.
(See the System Configuration Properties Reference document in the Polarion section of Support
Center for details.)
You can create new access tokens in the Security settings of your Profile in TFS. The user must be granted
READ and WRITE permissions for Work Items and have the Bypass rules on work item updates
permission.
You need to configure Project Collection and Project to configure a sync pair. When setting up a Sync
pair, the synchronization scope can only be limited using a WIQL query. If you don't use a WIQL query, you
sync all items, no matter their Work Item type. While the queries aren't mandatory, they're essential for
narrowing down what gets synchronized. The expected content is the "where" part of a WIQL query. See
Microsoft's Documentation for details.
Both Microsoft’s TFS and Polarion use directed links. This lets you group items in parent child relationships
like the following:
Tip
When mapping Polarion link roles to Microsoft TFS link roles use the ID, for example parent, of the
Polarion link role and the ID of the reverse direction (System.LinkTypes.Hierarchy-Reverse) of the
Microsoft TFS link role.
Unlike Polarion, Microsoft TFS also uses undirected links, where two items can share the same Related
role. When they are mapped to Polarion, they are assigned a direction: from the TFS item with the lower ID
number to the TFS item with the higher ID number.
Tip
When mapping Polarion link roles to undirected TFS link roles, use the ID of the Polarion link role, for
example relates_to and the ID of the undirected TFS link role (System.LinkTypes.Related).
When synchronizing with TFS you can create a hyperlink to the sync partner of an item.
With this mapping (left to right), for every item in TFS, there will be a hyperlink to its corresponding item in
Polarion.
To have hyperlinks on both sides, you must configure the same mapping for the other direction. (Right to
left.)
Introduction
We created the Polarion/Teamcenter Direct Integration to aid an increasing number of Polarion and
Teamcenter customers that author requirements directly in Polarion and want to integrate them with the
Teamcenter ecosystem.
You can use the Polarion/Teamcenter Direct Integration on its own or in parallel with the existing Linked
Data (OSLC) integration
Linked Data
Direct (OSLC)
Capability integration
Note
You can use the Teamcenter Product Configurator connector to apply and resolve variant conditions
against requirements.
Installation
Prerequisites
Before installing the integration, make sure that both Polarion and Teamcenter are installed, configured
and mutually accessible. This includes the following components:
Tip
See Installation and configuration in Polarion for detailed instructions.
• Teamcenter 13.3 & MBSE Integration Gateway 6.0 with following components installed:
◦ Model Management: (On the server)
◦ Gateway for modeling
◦ Common Integration Framework
◦ Teamcenter Direct Polarion Integration
Tip
See Installation and configuration in Teamcenter for detailed instructions.
Note
Confirm that you have the required prerequisites before installing the integration.
Procedure
[POLARION_HOME]
\polarion
\extensions
\com.teamcenter.direct.integration
\eclipse
\plugins
#=======================================================================
====
# Teamcenter Configuration
#
# TC_SERVER_URL -Defines the default Teamcenter Server URL
(Required)
# AW_URL - Active Workspace Client URL (Required)
# ACTIVE_HOST_URI_KEY - Active Workspace Client hostkey (Optional)
# STAGING_DIR - Define the cache and staging
directories (Required)
# BOOTSTRAP_URLS - FMS Bootstrap URL (Currently Required
but will be optional once CIS provide support)
# TEMP_FMS_DIR - Temporary FMS Directory (Optional) Ex. path of
%TEMP% vaiable
# TC_CLIENT_CACHE - Use Tc client cache as derby needs to
be true
# IS_TCCS - Flag to define if TCCS enabled
(Optional)
#=======================================================================
====
ACTIVE_HOST_URI_KEY=activehost
AW_URL=http://[YOUR ACTIVE WORKSPACE CLIENT URL]:3000
TC_SERVER_URL=http://[YOUR DEFAULT TEAMCENTER SERVER URL]/tc
STAGING_DIR=C:\\bhm\\staging
BOOTSTRAP_URLS=http://[YOUR BOOTSTRAP URL]:4544
TEMP_FMS_DIR=
TC_CLIENT_CACHE=false
IS_TCCS=false
#=======================================================================
====
# SSO Connection Variables
# ------------------------
# Set the following variables to define the target Teamcenter SSO
server,
# Application ID and SSO Session flag value.
#
# Below Fields are required if SSO enabled.
#
# TC_SSO_APP_ID - Defines the default Teamcenter SSO
Application ID.
#
#=======================================================================
====
TC_SSO_APP_ID=tc
Note
Polarion facilitates Siemens SAMAuth token authentication for communication with other
SAMAuth-enabled applications.
To set up SAMAuth authentication, follow the standard OAuth2 configuration procedure
and ensure that it includes the "tokenExchangeParameters" section with a
"tokenExchangeParametersSetting".
When configuring the SAMAuth Exchange Flow setting, explicitly utilize the
"usedFor=TcAuthentication" attribute.
See the OAuth2 technical reference section for further details on enabling the Token Exchange
flow for SAMAuth.
Procedure
1. Open the scope (project or global) that you want to configure the integration for and enter
Administration.
3. Under Form Layouts, click Edit beside the Work Item Type you want to configure the integration
for.
4. Add the following where you want the widget to appear in a Work Item.
<extension id="linkedTeamcenterItems"/>
5. Click Save.
Enable the Teamcenter widget in the LiveDoc Properties and Work Item sidebars
Procedure
1. Open the scope (project or global) that you want to configure the integration for and enter
Administration.
<extension id="linkedTeamcenterItems"/>
4. Click Save.
<extension id="linkedTeamcenterItems"/>
7. Click Save.
Install in Teamcenter
Procedure
1. Launch Teamcenter Environment Manager (TEM) with administrative privileges. Right-click the
tem.bat program icon and choose Run as administrator.
(Default path: Siemens/Teamcenter13/install/tem.bat)
2. Select Configuration Manager and click Next.
6. Expand the Extensions tree and then the Model Management tree and select Server.
8. Scroll down, select Teamcenter Polarion Direct Integration, and click Next.
9. Shut down the suggested services and all tcserver background processes, and click OK.
Caution
Do not shut down FMS Server Cache.
10. Enter the Password for the infodba user and click Next.
11. Make a note of the template files that are also installed and click Next.
The installation may take several minutes depending on the speed of your computer.
12. (Optional) Click Show Details to view what is happening in the background.
A confirmation screen appears with a path to the installation log when the installation is complete.
Configure in Teamcenter
To allow Polarion Test Case LiveDocs to properly be published to Teamcenter and correctly create
Test Cases (which are children of Paragraphs) in Teamcenter, add the following value to the
TCAllowedChildTypes_Paragraph preference in Product Configurator.
• IAV0TestCase
Procedure
proxy_module modules/mod_proxy.so
proxy_http_module modules/mod_proxy_http.so
Note
Revoking the Polarion system properties and Apache configuration as described above only disables
the Teamcenter connections.
The existing and previously configured Teamcenter Configurator template-based projects stop
functioning in Polarion, because the connection configurations are lost.
Getting Started
FAQ
Tip
Click the Polarion ID link to launch the item in Polarion in a new browser tab.
3. A Work Item can be used in multiple LiveDocs in Polarion. If I publish multiple LiveDocs to
Teamcenter that contain the same Work Item, does this integration take care of duplicates or
will one Work Item from Polarion create multiple requirements in Teamcenter?
In Polarion you can Freeze referenced Work Items and Branch LiveDocs that have different versions of
a single Work Item. To ensure that you are viewing the correct item in Teamcenter, each version from
every LiveDoc imported from Polarion has its own copy. The history is not shared in Teamcenter but
you can click the Polarion ID to view the artifact in Polarion and access its history there.
4. Will I, or a user of my choice be notified automatically when publishing LiveDocs to
Teamcenter?
Polarion does not support automatic email notifications for jobs, but you can click on Job's log to
launch the publishing log in a new browser tab.
You can always view the status of the Job Log in the Polarion Monitor.
5. Is a LiveDoc and all its artifacts published to Teamcenter or is something left out?
Currently Free text (body text that is not in a Heading or Work Item) and Wiki Blocks in a LiveDoc
are not visible in Teamcenter.
Tip
You can view Free Text and Wiki Blocks in the PDF snapshot of the LiveDoc uploaded to
Teamcenter.
6. Some specifications can contain thousands of Work Items. When they're being published to
Teamcenter could they potentially timeout? What happens if the connection between Polarion
and Teamcenter is lost?
• The current timeout window is eights hours so even large specification Documents do not time
out.
• If the Teamcenter or Polarion servers go down, an error appears in the publishing log, and you
must restart the publishing process when the connection is restored.
7. I published a LiveDoc to Teamcenter but when I try and republish an update, I get the following
error.
This message is displayed when you try to edit a field (in this case, the LiveDoc's title) that is beyond
your permission level.
8. How do I configure the mapping between Polarion and Teamcenter?
The mapping between Polarion and Teamcenter is handled through the
POLARION_BHM_INT_DEF_FILE dataset XML file on the Teamcenter server.
The connector publishes all images, tables, attachments, links and rich-text content within the Work Items
of the selected LiveDocs to Teamcenter in a read-only, Released state.
Note
• In Polarion LiveDocs Free text (body text that is not in a Heading or Work Item), and Wiki Blocks
are not captured in Teamcenter as objects. Instead, the information is visible in a published PDF file
attached to the Teamcenter specification.
• Currently, artifact changes made in Teamcenter do not get synced back to Polarion.
• See the FAQ section for answers to common user questions.
Procedure
1. Select the Polarion project that contains the LiveDoc you want to publish to Teamcenter.
4. Click (Settings) on the left of the toolbar and click Publish to Teamcenter.
Tip
If you publish a Requirement specification first and a test case specification later, links are still
established.
If you are already logged on to Teamcenter, the Publish to Teamcenter dialog box appears. If not,
you are asked to log on to Teamcenter in a new browser tab.
5. Click Publish.
The publishing time depends on the number LiveDocs, their size, and the number of artifacts they
contain.
6.
(Optional) Click Job's log to view the publishing progress.
Note
You can always view the status of the Job Log in the Polarion Monitor.
8. Switch to the Teamcenter browser tab and view the LiveDoc there.
Tip
Refresh your browser, or the LiveDoc (click on the top right) to ensure that you are viewing the
latest revision and to populate the Teamcenter link in the Document Properties sidebar or Work
Item Properties sidebar if it is your first time publishing.
Tip
You can also publish a single LiveDoc to Teamcenter while its open in Polarion.
The connector publishes all images, tables, attachments, links and rich text content within the Work Items
of the selected LiveDocs to Teamcenter in a read-only, Released state.
Procedure
1. Select the Polarion project that contains the LiveDoc you want to publish to Teamcenter.
3. Select the target Space's index page by doing one of the following:
Tip
If you publish a Requirement specification first and a test case specification later, links are still
established.
If you are already logged on to Teamcenter the Publish to Teamcenter dialog box appears. If not, you
are asked to log on to Teamcenter in a new browser tab.
Note
You can always view the status of the Job Log in the Polarion Monitor.
Tip
Refresh your browser, or the LiveDoc (click on the top right) to ensure that you are viewing the
latest revision and to populate the Teamcenter link in the Document Properties sidebar or Work
Item Properties sidebar if it is your first time publishing.
You can update a requirement LiveDoc in Polarion and republish it at any time to Teamcenter.
Updates are typically done when significant changes are made to the LiveDoc and must be communicated
or represented in Teamcenter.
Procedure
1. Select the Polarion project that contains the LiveDoc you want to update.
If the LiveDoc was published to Teamcenter, a link appears in the Linked Teamcenter Items section.
6. Click (Settings) on the left of the toolbar and click Publish to Teamcenter.
If you are already logged on to Teamcenter, the Publish to Teamcenter dialog box appears. If you are
not, you are asked to log on to Teamcenter in a new browser tab first.
7. Click Publish on the Publish to Teamcenter dialog box.
8. Click Close once published.
9. (Optional) To view your changes in Teamcenter, click the LiveDoc's link in the Linked Teamcenter
Items section of link in the Document Properties sidebar.
Tip
The letter after / in the link represents the number of revisions published to Teamcenter. (D means
that four revisions of this LiveDoc were published to Teamcenter.)
After publishing Polarion requirements to Teamcenter, you must refresh your browser. If you do not, the
Teamcenter link in the Document Property or Work Item Property sidebars is not visible the first time
you publish, or the revision letter is not updated if you republish.
When Polarion LiveDocs are published in Teamcenter, they preserve the hierarchy created in the original
LiveDoc.
You can create Teamcenter Trace Links to Polarion LiveDocs artifacts published in Teamcenter.
Note
See the Active Workspace Documentation on Support Center for more information on Trace Links.
In the Documentation tab, the Trace Link icon appears next to the artifacts with existing Trace Links.
• Click beside a linked item to open its Overview tab in a new browser tab.
Update in Polarion
If you want to make changes to a requirement, open it in Polarion and republish it to Teamcenter.
Procedure
• If the selection is a Work Item level artifact (like Titles, or Requirement Work Items), it opens in
the Work Item Editor.
If you want to configure Teamcenter Parameters or Variant rules, you must unlock a requirement.
Caution
Artifact changes made in Teamcenter do not get synced back to Polarion.
Procedure
1. Select one or more published Polarion objects in Teamcenter that you want to unlock.
You can do this in one of the following ways:
a. Select the requirement in the Tree with Summary view.
Note
The Modify Polarion Requirements template is provided as simple example.
This template processes the node that you select and the elements below it, and sets them as
editable.
4. Click Submit.
A dialog appears confirming that the selected object was submitted to a workflow and it is now
modifiable.
Caution
The text and structure of the Teamcenter requirement objects should not be modified because they
are changed the next time they are updated from Polarion. Modifications or updates should be
limited to relating parameters, assigning configuration rules and options, or other relations.
When you finish adding parameters or variant rules in Teamcenter, you must lock the workflow.
Procedure
Products are becoming increasingly more complex, and customers are demanding greater individual
choice. The Teamcenter Product Configurator is used to introduce and maintain variability across the
product suite at a given organization site. It allows you to manage variability and to ensure consistency
when authoring and qualifying product data. It defines and manages variability for a product from the
inception of requirements setting to the conclusion when an order is delivered to a customer. It allows you
to select features that are most important to customers. The variant data is independent of any application
domain, for example, CAD design or part planning.
Variability defined within the Teamcenter Product Configurator can be seamlessly used to configure
data ranging from System Driven Product Development (SDPD) to documentation, design, part master,
manufacturing processes and operations, and ultimately even manufacturing execution. Benefits of using
the Product Configurator reach far beyond engineering.
With the Teamcenter Product Configurator being a single variant backbone across the full product
definition lifecycle within Teamcenter, Polarion ALM also leverages this variability management capability
through this integration.
Tip
For more information about the Teamcenter Product Configurator, see Teamcenter's Documentation
To use the Teamcenter variants feature of the Teamcenter Product Configurator (or Teamcenter
Configurator for short) with an existing Polarion installation, make sure of the following:
Variant management in Polarion is centered around Polarion LiveDoc Documents and Work Items
contained in Documents. We recommend that you become thoroughly familiar with these features before
you begin working with variant management using Teamcenter Configuration Management.
Tip
To enable the Product Configurator in Active Workspace in hosted mode for Polarion clients:
You must install the Product Configurator Hosting feature for Active Workspace Client.
Procedure
Note
The above Polarion property must be set on the Load Balancer/Shared Services and Cluster Instance
Node servers.
Tip
The polarion.conf file location varies depending on your Linux distribution, but here are some
common locations:
• Debian - /etc/apache2/conf-available/
• Redhat - /etc/httpd/conf.d/
• Suse - /etc/apache2/conf.d/
<IfModule !proxy_module>
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
</IfModule>
<IfModule !proxy_http_module>
LoadModule proxy_http_module /usr/lib/apache2/modules/
mod_proxy_http.so
</IfModule>
Note
The above Apache modules must be set on the Load Balancer/Shared Services server.
Note
The above must be set on the Load Balancer/Shared Services server.
Tip
You must restart both the Polarion and Apache services if you change the Polarion system
properties or the Apache configuration.
Deployment: Polarion - Standalone / Cluster with Teamcenter servers under (TCSS) Single sign-on
Tip
We recommend configuring Polarion and Teamcenter servers under Teamcenter Security Services (TCSS)
Single Sign-on behind a reverse proxy/load balancer server.
Procedure
• Polarion property to connect to Teamcenter Services through reverse proxy / load balancer server:
base.url= https://<reverse-proxy-host>.<fqdn>
com.siemens.polarion.tc.uri=http(s)://<reverse-proxy-
host>.<fqdn>:<port>/tc
Example:
com.siemens.polarion.tc.uri=https://reverse-proxy-
server.net.plm.com:7002/tc
• The Polarion property to configure Teamcenter & Polarion Servers within Single Sign-On (TCSS)
com.siemens.polarion.security.appId=<PolarionAppID>
com.siemens.polarion.tc.sso.app.id=<TeamcenterAppID>
Example:
com.siemens.polarion.security.appId=Polarion
com.siemens.polarion.tc.sso.app.id=TC
Note
The above Polarion properties must be set on the Load Balancer/Shared Services server.
<Location /Polarion>
ProxyPass http(s)://<polarion-host>.<fqdn>:<port>
ProxyPassReverse http(s)://< polarion-host>.<fqdn>:<port>
</Location>
3. Configure the content security policies on the Polarion and Teamcenter servers.
• Configure Polarion web server (Apache) to return the Content-Security-Policy HTTP header and
make sure it contains the frame-ancestors directive with 'self' 'teamcenter server' and
'reverse proxy server’ defined.
Example:
The Teamcenter server (https://teamcenter.example.org) is integrated with the Polarion
server (https://polarion.example.org) through a reverse proxy server (https://
reverse-proxy.example.org).
So Polarion's web server should return the following directive in the Content-Security-Policy HTTP
header:
frame-ancestors 'self' https://teamcenter.example.org:3000 https://
teamcenter.example.org:7002 https://reverse-proxy.example.org
Note
Depending on the configuration of Teamcenter's server deployment, you may need to specify
multiple ports.
Procedure
proxy_module modules/mod_proxy.so
proxy_http_module modules/mod_proxy_http.so
Tip
Changing the Polarion system properties and revoking the Apache configuration as described above
only disables the connections of Teamcenter.
Projects based on the Teamcenter Configurator template that already exist and that have
been previously configured in Polarion stop functioning because of the missing connection
configurations.
The Teamcenter Variant Management feature comes with a project template with predefined support
for variant management using Teamcenter Configuration Management. The Specification Project
with Teamcenter Variant Management (Requirements, Testing) template is specifically designed for
creating variant management projects using Teamcenter. It includes a guide on how to use Teamcenter
Configuration Management in Polarion.
Creating a Teamcenter Variant Management project is no different from creating any other type of
project. Simply select the Specification Project with Teamcenter Variant Management (Requirements,
Testing) template that supports variant management in the New Project wizard page.
For more information about creating projects, see Create a new project from a template.
The Teamcenter Configurator window can be accessed in Document view, Tree view, and Table view by
clicking Teamcenter Configurator.
You can map the Master Document using the Teamcenter Configurator Context ID (Item ID) as shown in
the screen below.
You can add Variant Conditions to a requirement in the Variant Management section of a Work Item.
The Feature Model from Teamcenter is displayed by using Ctrl + Space as shown below.
You can also use the Work Item Editor or the Work Item Properties sidebar in a Document to set the
variant condition.
Edit Variant conditions using the Active Workspace Variant Condition Editor
You can use the Variant Condition Editor hosted in Teamcenter and embedded in Polarion for editing
Variant Conditions.
The Variant Condition Editor window can be accessed in Document view, Tree view, and Table view by
clicking Variant Condition Editor. You will be redirected to the Active Workspace login page.
After successfully logging in, the Active Workspace Variant Condition Editor is displayed, where you can
edit Variant Conditions.
You can select the Work Items that you want to edit, and they are added to the Variant Condition Editor
dynamically.
In Document view:
In Table/Tree view:
Procedure
1. You can edit Variant Conditions by clicking in the Variant Conditions Matrix.
2. You can save the edited Work Items by clicking . The edited values are saved in the Variant
Condition field.
3. All previous edits to the Variant Conditions are shown in the Variant Conditions Matrix.
The Variant Condition Editor can be used to validate Variant Condition values based on the constraints
added in Teamcenter. See the following link for more information about constraints in Teamcenter.
You can validate all Work Items at once by clicking in the Active Workspace Variant Matrix. The
icon is added to the column header of Work Items that had initial violations. The error message is
displayed as a tooltip.
You can validate a single Work Item and get a more detailed error message. Validate a single column that
A Generated Variant Specification Document contains the Configurator Saved Variant Rule (SVR)
Name from which it has been generated. This information is included in the Document Properties sidebar
under Tc Variant.
The Generated Documents of a project are under the Output – Variants section of the Variant
Documentation Space.
You can get the list of Generated Documents for a particular Configurator SVR Name by doing a query.
You can hide and display the Configurator namespaces when editing and rendering a Variant. You can
control this feature by setting the TC_show_family_namespace_prefix preference. By default, this
preference is set to OFF (False), so you do not see namespace names for Feature and Family while using
the Text Editor.
To see namespaces alongside Feature and Family names for a configured Teamcenter Configurator
Context ID, set the above TC_show_family_namespace_prefix preference to ON (True).
Procedure
1. Load the Master Specification. (Create a Master Specification or use an existing one.)
7. Select a Saved Variant Rule (SVR) from the list and click Next.
The Define Target Documents dialog box appears.
Tip
The Monitor topic lists all variant document generation jobs under the name Generate Variant
Documents. When processing large master Documents, you can track the respective jobs that
generate the variant Documents via individual logs under the topic. The Document(s) appear in
the target Space when processing is complete.
You can use a Propagation Link on the Variants administration page to define the relation between
Requirements and Test Cases. This relation is used to configure a Test Case when its linked Work Item is
configured using the feature or family defined in Teamcenter.
To integrate existing Polarion projects with Teamcenter Configurator, you must add custom fields to
Documents and Work Items and edit the Work Item form layout for Work Items that you want the
Variant Management to appear in.
Procedure
1. Open Administration, expand Documents and Pages, and select Document Custom Fields.
Tip
See Configure Document custom fields for more information.
Procedure
Tip
See Configure Work Item custom fields for more information.
Update the Form Layout configuration of Work Item types to add the Teamcenter Variant Management
section.
Procedure
Tip
Ensure that <pvRestriction> is NOT in the form layout configuration for Polarion projects you
want to configure for Teamcenter Configurator integration.
(See the Configure Work Item Form Layout section for more information about Work Item
configuration.)
Teamcenter Share
Prerequisites
You must confirm or configure all of the following to enable Teamcenter Share in Polarion:
• Teamcenter Share authentication must be configured in the authentication.xml file via Oauth 2.
Caution
If you configured Teamcenter Share with Polarion 21 R2 (using Polarion properties) you must do the
following:
1. Delete the old configuration from the Teamcenter Share Admin Console's Product
Configuration section.
• The Installation URL in the Teamcenter Share Admin Console must be formatted as follows:
protocol://host[:port]
(Without the /polarion path ending.)
Tip
Check the For Teamcenter Share section in the Connectivity table for your firewall topic to ensure that
your firewall doesn't prevent Polarion and Teamcenter Share from communicating.
If your Polarion load balancer's Apache configuration has a defined Content Security Policy, you must add
https://acc.collab.sws.siemens.com (the Active Cloud Component provider URL) twice to the
Content-Security-Policy header. (For both the HTML script and style elements.)
Example
Configuration Properties
Polarion's system configuration properties affect how various Polarion system processes and functions
work or behave. Most of these properties:
However, there is a small subset of "runtime" Configuration Properties. They differ in several key ways:
• They can affect the system either globally, or only for some specific project(s).
Procedure
1. Open Repository or a Project, depending on which scope you want the settings to affect.
Tip
If you want a runtime property setting to apply to multiple projects, but not globally to all projects,
you need to set the property in each of the desired projects.
Results
This is the page where administrators can add and update the runtime Configuration Properties.
The properties can be set to affect a specific Project, or the Repository. Values that are not explicitly
set in the project scope are inherited from the Repository (global) scope.
Note
• When viewing the Configuration Properties page for a project, only properties that are set for that
project appear on the Administration page.
• View the page in the Repository (global) scope to view all properties that are inherited by all
projects.
Reference documentation
All the Configuration Properties are documented in the Polarion System Configuration Properties
Reference, a PDF document available on the Documentation page of the Polarion product center on
Support Center. An updated version of this document is published with every Polarion release. Only
currently active properties appear in each edition. The runtime properties appear in a separate section of
the document.
System maintenance
Polarion monitors Java system memory and disk storage resources and automatically notifies the Polarion
administrator by email when one or both of these are approaching failure levels. The actual algorithm is
fairly complex. The main points you need to know as an administrator are:
• A warning message is sent if the available free disk space is running low. By default, notifications are
sent when free disk space:
◦ is less than 5%
◦ is less than 1 GB
◦ less than 100 MB
The free disk space limit is configurable. See configure free space limit, below.
• If Java is not able to recover enough heap memory during garbage collection, conditions may indicate
that Polarion is running out of memory, and the administrator may want to increase the -Xmx setting in
polarion.ini (Windows) or etc/config.sh (Linux) and restart the server.
Therefore, a warning message is sent when Java heap space is less than 5%.
Caution
If Polarion installed as a service, as it is in the default Windows installation, you will also need to
uninstall then reinstall the service.
Procedure
The email address(s) for the recipient(s) of these notifications can be set
by specifying a comma-delimited list of email addresses in the system
property:com.polarion.platform.monitoring.notifications.receivers
It is not enough to simply set this property. Monitoring of system resources must be configured as well.
The following system properties should be set:
com.polarion.platform.monitoring.notifications.disabled=false
com.polarion.platform.monitoring.notifications.receivers=<valid@email>
Some processes, poorly optimized custom reports in particular, can run for hours and consume valuable
server resources. The problem is compounded when users get impatient and refresh the view in hopes that
it will speed up the process. At best, these multiple parallel runs slow down the server. At worst they can
completely deplete the server's resources and result in an out of memory error that requires reindexing the
server. To prevent clogging of the server, Polarion provides functionality that interrupts the processing of
UI requests that take longer than a specified amount of time.
Note
Only read-only user requests are affected. Requests with write operations are not.
The system properties described below prevent the clogging scenario by killing any user UI requests a
few seconds before the connection timeout defined by the Apache configuration expires. They display the
following error:
Your request [id: REQ_<NUMBER>] took too long to process and was stopped to avoid clogging the server.
Possible reasons it took so long: High server load, too much processed data or non-optimal scripts.
The interrupted request will also be logged in the log files. The following exception indicates such a
request interruption: com.polarion.core.util.exceptions.OperationTimeoutException
The information in the exception and stack trace might indicate why the request is taking so long to
process. Use the request identifier REQ_<NUMBER> to match the request and log record.
The following system properties can be used to prevent long running transactions.
• com.siemens.polarion.platform.threadKillingMode=killAll
The desired kill mode for an execution thread monitoring request.
Possible values:
◦ killAll: (The default setting.) All long, read-only UI requests will be killed.
◦ reportOnly: Only requests related to Rich Text or Wiki Pages (read-only) will be killed.
◦ disabled: Only logs the long-running transactions and doesn't interrupt them.
• com.siemens.polarion.platform.threadKillingLogStackTrace=false
Define the thread killing log's level of detail.
◦ False: (The default setting.) The log file only mentions that a thread was killed/interrupted.
◦ True: The log file will also contain the stack traces of threads that were killed/interrupted.
• com.siemens.polarion.platform.threadKillingTimeout=590000
Sets the time period (in milliseconds) after which a request can potentially be killed.
The default value is 590000 (9 minutes, 50 seconds: 10 seconds before the default Apache timeout). If
the value is 0 or less than 0, the default value will be used.
Note
• Set this property with a time period less than the Apache ProxyPass timeout value configured in the
polarion.conf or polarion-cluster.conf files.
• UI requests that make any write operation are marked as non-interruptible and will continue to be
processed in the background until they are complete.
• Custom extensions invoked by UI requests that operate outside the Polarion API may also be
considered interruptible.
(If you think that they might exceed the set timeout period and be affected by a termination of
the request, then disable this feature or call the preventThreadKilling() method from the
ITransactionService class within the custom extension.)
Administrators can schedule an automated cleanup of the Activity Stream storage area. The default setting
runs the Activities Index Cleanup job on a weekly basis, every Sunday at Midnight. Reasons to clean up this
index include:
• The bigger the index, the slower read and write operations become.
• In a clustered environment, the index is located in a shared storage environment. If never cleaned, it will
grow indefinitely.
Note
In a single-instance environment, the activities index is cleaned with every reindex.
By default Activity Cleaner job keeps a maximum of 5000 activities that are not older than 90 days for
each source.
These limits can be configured granularly per source and type by editing the following lines in the
polarion.properties file.
In (C:\Polarion\polarion\configuration\) by default.
maxActivitiesLimit=5000
(Can be set individually for particular sources and types, or globally for all sources.)
maxActivitiesAge=90
maxActivitiesAge = How long, in days, that activities are preserved by the Activity Cleaner.
(Can also be set individually for particular sources and types, or globally for all sources.)
See Configure the Scheduler topic in for more information on scheduling maintenance jobs.
Polarion comes with a default set of scheduled jobs. Scheduler allows you to configure scheduled jobs
such as builds, dashboard updates, system cleanup, etc. You can alter the properties of scheduled jobs,
such as the day of the week when the job should run. You can also add additional scheduled jobs to the
default set, or remove jobs from the default jobs set. You can optionally invoke any job explicitly in the
Monitor topic.
This configuration is available only for the global (repository) scope. If you are not familiar with the
basics of the different scopes, you may want to review: The Administration Interface. The configuration is
specified in the Scheduler topic of Administration.
Procedure
Caution
Jobs configured to run during a daylight saving time change might result in them being skipped or run
twice.
Example:
Jobs set to run between 1 and 2 am during a time change are skipped when the server time jumps from
1 to 2 am.
Jobs can spawn other jobs. The ID for such a job is multi.job. Jobs to spawn are referenced by their
names from schedule.xml. It is possible to run jobs either sequentially (default) or in parallel, and
possible to terminate sequential execution if a job fails. Default is to ignore the failure. The job reports
failure if at least one of the executed jobs fails.
<jobs>
<job>_JOB_NAME_</job>
. . .
</jobs>
</job>
It is possible to fail the job if at least one of the executed jobs fails. Default is to finish successfully no
matter what. Aborting will always fail the multi.job.
You can set whether to fail multi.jobs if a child job fails by using the delegateFailure option. Whether
it terminates immediately depends on the terminateOnFailure option.
Extended configurability:
For example: J1,J2|J3|J4,J5 will execute three groups of jobs in parallel. The first group consists of
sequence J1,J2, the second group is a single job J3, and the last group is a sequence of J4 and J5.
Scheduled jobs should be reviewed for a multiserver cluster, and convenient Node selectors (the node
attribute of <job> elements) should be specified depending on the nature of the job. The following
default jobs should have node="*" specified for them in a clustered setup:
• Index Checker
Tip
You can also specify the node that you want to run a job on.
node="<nodename>"
You can define a job that runs a custom script. The job ID in the scheduler must be script.job. Groovy
(groovy) and JavaScript/ECMAScript (js) scripts are supported. Script files must be stored in the scripts
folder of the Polarion installation's file system.
• logger: A com.polarion.platform.jobs.ILogger you can use to log messages for the job
• scope: A com.polarion.platform.context.IContext that represents the scope of the job.
• workDir: A java.io.File pointing to the working directory of the job.
• jobUnit: The com.polarion.platform.jobs.IJobUnit that runs the script.
Every property is defined inside the <properties> element of the job. The property in the
example below would be accessible as variable with the name myProperty containing the value
myPropertyValue.
Tip
Looking to unblock some methods called in job scripts?
The internal script engine that executes scripts via jobs, and also script-based workflow conditions and
functions for Work Items and Documents (ScriptCondition, ScriptFunction) can run a script without
installing it into the scripts folder. To run a script directly, direct your web browser to: [POLARION
SERVER]/polarion/scripting (where [POLARION SERVER] is replaced with the actual domain of your
server).
The page provides an interface that you can use to input and run a script. The variables visible to
the script are the same as for script jobs. (Actually, the script is run as a job). The system property
com.polarion.scripting.servlet.enabled must be enabled in the system properties file in order
to run scripts directly. By default, only administrators are allowed to run scripts this way, as it is potentially
dangerous.
As mentioned, Jobs are defined (scheduled) and run in the global scope. You can start or stop the
Scheduler from the Scheduler topic in Global Administration.
Procedure
2. Enter Administration.
3. In the Open Project or Project Group dialog box, select Repository to work in the global scope.
A button appears at the top of the Scheduler page, just under the main heading. If the Scheduler
is currently running, the button label is Stop Scheduler. If the Scheduler is currently stopped, the
button label is Start Scheduler.
4. Click the button for the operation you want to invoke. When the Scheduler is stopped, configured
scheduled jobs will not run. When the Scheduler is started and running, the configured jobs will be
run according to the configured schedule.
You can run any scheduled job immediately from the Monitor topic. The Scheduler must be running (see
Starting and Stopping the Scheduler.) Check the job(s) you want to run in the Scheduled Jobs section
and click the Execute Now button to launch the job(s) you selected.
Caution
Running jobs uses server system resources, and some types of jobs can be very resource intensive.
Administrators generally schedule jobs to run at times when user demand is low. Be aware that explicit
running of jobs has the potential to degrade performance for end users, and use discretion accordingly.
You can use the execute.command job to immediately run some system command or utility. For example,
the following will run the PDT diagnostic utility.
When set to False, users will not be able to run execute.command jobs, and will be prompted with a
security warning if they attempt to do so.
Note
The Polarion Diagnostic Tool is also an execute.command job, which will also be disabled.
You can see the status of all Jobs in the Monitor topic. This topic is available in the Navigation pane
when you exit from Administration and return to project or portal content topics.
Procedure
1. In the Open Project or Project Group dialog, select either Repository or a Project (you must have
the relevant permissions).
2. If you are in Administration, click the link in the top panel of Navigation to return to the portal
Home or the project.
Jobs create temporary folders, which in turn store job logs. At some point, you will want to clean up these
folders. There is a job jobs.cleanup that deletes these temporary folders and their data. The job can be
scheduled to run periodically, or launched explicitly. You can optionally use the preserveAgeHours to
specify how long to preserve temporary file after jobs start. The value of the parameter is hours (see the
following example). If the parameter is not specified, the job defaults to 24 hours.
The optional preserveFailedAgeHours parameter handles Failed jobs separately, so they are
not deleted with the other temporary folders. Otherwise, the parameter works the same way as
preserveAgeHours. If not configured, the failed jobs are not preserved separately.
Example:
In this example, temporary folders and data are preserved for 36 hours, and folders of Failed jobs are
preserved for 72 hours.
Deprecated Jobs
Note
The following is a list of jobs that used to be preconfigured in the schedule.xml file but are now
deprecated and scheduled for removal.
<localDeploymentSpaceName>_default</localDeploymentSpaceName>
</job>
The following sections describe how to Backup and Restore indexes used by Polarion, including the Lucene
Index, the PostgreSQL database, Polarion Object Maps, and so on. If Polarion malfunctions, these data
can become corrupted, and users must run Reindex to recreate the data. Polarion has integrated tools to
backup these indexes and to restore them in a swift manner, however, this feature does not backup any
customer-related data.
Procedure
Procedure
Procedure
Procedure
Procedure
Example
• folder: The path to the folder with backups archives. The default value is backup in the Polarion
data folder (see com.polarion.data value).
• tempFolder: The temporary folder where all backup parts are collected. The default value is the
user's tempdir.
• workers: The amount of threads dedicated for the backup. The default value equals the amount
of available processors.
• postgresCommand: The PostgreSQL command for executing the backup. The default value is
-F t -z -X s. Port, host, and user are automatically added. For more information, see
pg_basebackup options.
• postgresTimeout: The maximum time for executing a PostgreSQL backup in minutes. The
default value is 240.
• removeNodeFromCluster: Removes the cluster node from the load balancer. This optional
parameter can be used when the backup job is executed on the cluster's node. The default value is
false.
Note
For more information on how to configure a job for a specific node, see Jobs in a cluster setup.
Procedure
Note
The restore script can only be run with a local PostgreSQL installation present.
Procedure
1. Stop Polarion.
2. Stop PostgreSQL used for Polarion.
3. Open your terminal application, and go to the directory of the restore script. [POLARION HOME] is the
directory where Polarion is installed.
• For Windows: [POLARION HOME]\polarion. For example: C:\Polarion\polarion\.
• For Linux: [POLARION HOME]/bin/. For example: /opt/polarion/bin/.
4. Run the restore script as a user with administrator privileges, with the -backupFile argument
pointing to the path of the backup file to be restored:
• For Windows: restore.bat.
• For Linux: restore.sh.
You can use the following options:
• -restoreDir <path-to-restore-home>: The path to the restore home folder used for
temporary files and logs. This attribute is optional. If the option is not set, the user's temp folder is
used.
• -data <path-to-data-directory>: The path to the Polarion data directory. This attribute
is optional. If the option is not set, the tool will try to resolve the data folder in the Polarion
installation.
Wait until the script finishes successfully.
5. Start PostgreSQL used for Polarion.
6. Start Polarion.
Procedure
1. Stop Polarion.
2. Stop PostgreSQL used for Polarion.
This topic discusses the system location of data that administrators should be sure to include in regular
backup operations.
For the purposes of discussing the location of various folders that administrators may wish to include in
backups, let's define some placeholders and their meaning on different operating systems The installation
file system structure differs somewhat on Linux and Windows.
The following table describes placeholders and their locations on different operating systems.
Note
The above paths are the defaults. You can configure the actual locations during installation.
Subversion repository
An essential component to back up is the Subversion repository. Linux location: [POLARION DATA]/svn.
Windows location: [POLARION DATA]\svn. The default storage method is file-based and so does not
modify existing files, only adds new ones. This is very convenient for incremental back-up methods.
Project builds
The contents can be very large. Developers and project managers should know what is most critical to back
up. It is usually not necessary to back up all the nightly builds for example. It also makes sense not to back
up the demo project builds, if these have been installed.
Reports
Reports are generally not critical to back up because they can be recreated any time, with one important
exception: the trends.
To back up the trends you need to collect all *trend*.xml files —.such as workitems-trend-
data.xml — in the structure beneath the folder [POLARION DATA]/RR (Linux) or [POLARION DATA]
\RR (Windows). Backing up the entire folder will most likely be a significant waste of backup space (up to
99%).
If you use the SCRUM calculation, you should back up scrum-data.xml because it holds the historic
values for all past sprints.
User-modified data
The following data may or may not need to be backed up depending on whether it was modified after
Polarion was installed.
System It may make sense to back up the root system configuration file polarion.properties
configuration (follow link for location). This file can be recreated by reinstalling Polarion and filling
properties file in all the original arguments. However, if the file was modified after the installation to
customize the system configuration, it is a good idea to back it up.
Modified If the original folder structure of the installation was modified — to add more Maven
installation plugins or Apache modules, or if some graphics or templates were modified — it is
structure a good idea to back up such modifications in case it is ever necessary to reinstall
Polarion — on new hardware, for example.
Connectors data
If any Connectors are configured for any projects (in Administration Connectors), include the
folder [POLARION DATA]/synchronizer (Linux) or [POLARION DATA]\synchronizer (Windows)
in your backups. The folder contains a database that stores the relation between Work Items and the
items in the connected third-party systems, and also Baseline data that is used to detect which fields
were changed. Losing that data would mean losing the relation between Work Items and the items in the
other systems, and when the items are synchronized they will be recreated instead of updated, thereby
corrupting the data integrity of both systems.
1. Do a snapshot of suspended virtual machine in which Polarion server runs (in cases where virtual
machines like VMWare are used).
2. Stop Polarion server, do the backup, run server again.
Warning
On Windows, do not use backup software that opens files in write mode, because that may cause
corruption of index-related files, which would then require a reindex operation afterward.
If running on Windows, and backup software does open files in write mode, configure the job Live Plan
Refresh not to run during the backup. That job is most likely to work with the index, and stands the
greatest chance of index corruption resulting.
Note
The Live Plan feature was removed in version 21 R1. However, the Live Plan Refresh job was not
removed from the code base, but rather disabled in the default configuration. If this job is still configured
to run on your system, you should remove it.
When doing recovery from a backup of the running system (not a snapshot of the virtual machine, or
the server was not stopped during the backup), it will most probably be necessary to reindex the system
afterward.
Polarion stores all data in the integrated Subversion repository. While this approach brings many
advantages compared to a traditional database approach, it does entail some performance trade-offs.
Polarion uses advanced caching and indexing techniques to achieve acceptable performance levels. In
most standard situations, the caching and indexing behaves transparently and administrators do not need
to take care of it. However, the caching and indexing logic imposes certain restrictions and requirements
for what you can and cannot do. This topic explains these limitations in more detail.
Index Synchronization
The index contains information about location of all entities in the repository and their history, so the term
index refers to more things then just the index used by the Search feature. Rather it is the entire indexing
scheme that enables optimal performance.
During the index update, Polarion checks all changes made to repository since the last indexed revision,
and updates the index accordingly.
Changing sort order of an enumeration, dates of time points, and similar items that are already referenced
will cause inconsistency in the sorting. Some referrals will be sorted by the old sort order, and some by the
new. A complete index rebuild solves this problem.
Note
If all you need to do is refresh lists of enumerations because of changes to some enumeration(s), you
do not necessarily need to run a full re-index. For more information see: Enumerations and Database
Issues.
Symptoms of a broken index tend to be things like some Work Items are not up-to-date, some are missing,
History cannot be viewed, or shows invalid or truncated information.
If you observe the above symptoms you may not need to completely rebuild the index .
1. Try an index refresh on the repository, or on a specific project. This corrects problems with
information updating.
Go to the Administration interface and open the Repository (if you want to refresh the entire
repository), or a project (if the problem seems to affect only that project). Then, in Navigation, select
Maintenance. In the Index section, check the index(s) to refresh and click Refresh Index.
Tip
The indexes listed varies depending on whether you are working in global or project scope.
2. If number 1 above does not fix all symptoms, try the Check Index button. The index check job should
bring back Work Items that are missing from view.
If the above steps do not fix the symptoms, then you will need to rebuild the full index.
The procedure may sometimes be referred to as "index rebuild", "rebuild index", "index synchronization", or
"index rebuilding".
There are two important things for an administrator to keep in mind before initiating an index rebuild:
• The Polarion server must be shut down before commencing an index rebuild.
• Depending on the size of the repository, reindexing time can range from a few minutes to several hours.
End users will not be able to use the system during the reindexing process.
If possible, you should plan to perform any re-index operation at a time when system usage is low, and
downtime is not critical for end users.
Users cannot use the system while the system indexes are being rebuilt. They can, however, use the
system while the historical database is being reindexed.
The embedded historical SQL database, which replicates the Subversion repository to facilitate complex
queries, is indexed in the background. Although users can use the system, some features are either not
available, or do not display information until the database reindex is complete. A message is displayed at
the top of the Navigation panel warning users that database indexing is in progress.
Caution
While a historical database indexing is in progress (the DB History Creator job is running), you should
be aware of the following:
You can configure how many CPU cores (workers) are used in the phases of the indexing and startup
process.
• The default configuration uses a workers value equal to the number of available CPU cores on the
machines.
(We determined this was the optimal setting because it utilizes 100% of the CPU to complete a reindex
in the shortest amount of time.)
• Polarion also automatically re-configures the database connection pool to double the number of CPU
cores.
• Under special circumstances, you can adjust the number of parallel workers via the
com.polarion.startup.workers property.
(Especially if advised by our performance experts.)
• If you reconfigure the number of startup indexing workers, make sure that:
1. maxPoolSize = 2x the workers count
(Otherwise, Polarion does not have enough database connections to feed data into the database.)
Use the following property in the polarion.properties file to set the maximum pool size for
PostgreSQL connections.
◦ com.siemens.polarion.platform.sql.maxPoolSize
The following rules are used if the value is not defined:
1. If the number of processors * 2 is less than 10, the value used is 10.
2. If the number of processors * 2 is more than 20, the value 20 is used.
If the value is defined, the following rules apply:
1. If the defined value is less than 10, the value 10 is used.
Warning
If the value is more than 20, the user MUST adjust the max_connections value in the
PostgreSQL server configuration to a number that is more than 4 times the value used.
You can also specify different numbers for individual phases in instances of the following system property:
Caution
The following phase-specific deviations should only be used under very special circumstances.
Please consult with Polarion support before adjusting the default settings.
com.polarion.startup.workers.phase#
Note
It is possible to control which attachment file types have their content indexed, or to exclude specific
file types from such indexing.
For more information, see Attachment file types for indexing.
By default, the number of CPU cores used for the above phases is the total number of cores available to the
Polarion.
In the default setup, the jobs are configured to run only between 19:00 and 08:00, and they can be
stopped and started by scheduled jobs.
(So in most cases there should be no need to redefine the number of workers.)
Adjusting the number of workers may be worth doing for the jobs running after Polarion start-up that may
cause performance to slow.
To explicitly set core usage for all index phases and/or the configurable index phases listed above, you must
add the following lines to the system properties file polarion.properties:
◦ com.polarion.startup.workers.phase10=3
You perform the reindexing by running the appropriate reindexing script for your operating system. Be
sure you shut down the Polarion server (Polarion Service) before running the script.
Progress of the reindexing operation is reported in the console and written to a log file.
Warning
Do not interrupt the index rebuild process. The process writes messages to the console and the log4j-
startup-TIMESTAMP.log file. Check this file for the status of the process. As mentioned, with large
repositories the index rebuild can take several hours, and it may seem that nothing is happening for long
periods.
Reindex must be restarted if interrupted. If you believe there may be a problem with the process, contact
Polarion technical support on Support Center before attempting to kill the reindex rebuild process.
Polarion comes with a self-diagnostic utility, Polarion Diagnostic Tool (PDT) aka Diagtools. If your system
is not performing as it should, you can use this tool to run comprehensive diagnostic tests. You can then
send the results to the technical support team. Diagtools checks if Polarion is running in a cluster and
gathers configurations from shared folders.
Generally, you should run PDT when opening a new support case on Support Center and the issue isn't
just a how-to question.
The utility is bundled into all product distributions. It is located in the diagtool folder under the root of
your Polarion installation. PDF documentation covering setting up and running the PDT utility is included in
that folder.
Warning
• If administrators disable all execute.command jobs the Polarion Diagnostic Tool is also disabled.
• There are periodic updates to Polarion's Diagnostic tool, and while it's updated automatically along
with Polarion, you must update it manually on the Shared services machine in a Clustered setup. Just
overwrite the Diagtool folder on the Shared Services machine with one from an updated Node.
Over time, your server's disk storage can accumulate a large amount of Polarion data that does not need
to be kept. For example, if your process involves nightly or other frequent builds, these can eventually
consume a lot of disk storage, but they don't really need to be kept indefinitely, or can be archived
somewhere else if they do. Old log files can also consume disk space. This section discusses ways to clean
up your server's disk storage and recover disk space.
Polarion comes preconfigured with the build.clean job for cleaning up builds and related things like
local deployment space.
To have the job delete the local deployment space directory, set the localDeploymentSpaceName to
the name of the local deployment space. For example:
To have old builds deleted from BIR, three job parameters must be set:
• maxBuildAgeDays,
• minSuccessfulBuildsCount,
• buildArtifacts.
The job deletes builds of all build artifacts that match at least one of the selectors from buildArtifacts,
but only those builds that were started at least before maxBuildAgeDaysdays. At least the
number of builds specified in minSuccessfulBuildsCount are preserved provided at least that
number of successful builds exist — builds with status OK, for example. Build selector format is
GROUP_ID:ARTIFACT_ID, where each part can include a suffix * matching any string. For example:
You can configure and run the logs.cleanup job to delete log files with specified names that are older than
a specified date. (See Configure the Scheduler for more information on working with scheduled jobs.)
The following example shows the basic structure of the log cleanup job configuration.
<job name="_ARBITRARY_JOB_NAME_"id="logs.cleanup"
cronExpression="0 15 10 ? * MON-FRI" scope="system" disabled="true">
<maxFileAgeDays>_MAX_AGE_OF_FILE_IN_DAYS_</maxFileAgeDays>
<filePatterns>
<filePattern>_FOLDER_|_PATTERN_</filePattern>
... <filePattern> ...
</filePatterns>
</job>
Tip
Larger enterprise organizations, especially those subject to regulatory oversight, should also consider
using an external central monitoring application for saving and archiving logs.
File name prefix is matched against all files in the folder, those matching the same prefix are treated
together, From this set, all files older than _MAX_AGE_OF_FILE_IN_DAYS_ are removed with the
exception of the newest one which is always kept.
Job result:
Job result:
Tip
• Updating to the latest repository format can provide improvements (a small increase in performance
for specific scenarios and a few % of space saved in the repository), but the migration can be
time-consuming.
Recommendation: Don't do it while updating Polarion. Instead, update it during a scheduled
maintenance cycle.
• Use the latest version of SVN 1.14 in production environments.
(Older versions like 1.7 significantly impact performance.)
With the official support of Subversion 1.10+, we also support and recommend migrating your production
repositories to the latest repository storage format introduced in Subversion 1.10.
The fastest way to migrate a repository to the new format is to “pipe” the output of the svnadmin dump
command right into the svnadmin load of the new repository. In our labs, we were able to migrate a
production repository of close to 500 GB and 4.7 million revisions in less than 15 hours.
The new repository format uses a different compression algorithm, which is faster but less efficient.
Depending on the repository's contents, its size might grow by up to tens of percent after the migration.
Our tests with production repositories show that the growth is typically below 10% of the size while
increasing the throughput for read and write operations by 5 – 10%.
Procedure
Tip
• You should secure access to the repository via the configuration in: repo_path/conf/
svnserve.conf.
• Make sure that the new repository has the same permissions and owners as the old one.
3. Load the old repository contents from the dump to the new repository via command: svnadmin
load -M 1024 repo_path < dump_file.out
(The in-memory cache (-M) option was introduced only in SVN 1.9.)
This operation may take days for large repositories with hundreds of thousands of revisions, so use
the in-memory cache and fast storage (SSD) for this operation. Doing an incremental dump and load
when switching the repository can help you to limit the downtime.
4. Pack the repository after import.
Introduction
• Operating system
• Java Virtual Machine (JVM)
• Apache HTTPD
• Polarion-specific
Polarion comes with very basic monitoring features like Low resource monitoring notifications. For
better results, we recommend connecting Polarion to an Enterprise monitoring tool that lets you monitor
the server's overall health (CPU usage, memory consumption, Apache threads) and Polarion logs so you
can identify ERRORs early and act appropriately.
To keep your deployment under control, we recommend keeping your logs ERROR clean:
You should aim to either fix your configuration so that it does not trigger ERRORs or report the ERRORs to
Support so they can be fixed if configuration changes can't solve them.
Here's how the DevOps administrators of the Polarion research and development team monitor in-house
Polarion deployments to gauge performance and predict potential problems.
Caution
Sharing this knowledge and experience gained by our DevOps can provide a starting point for
administrators interested in setting up performance monitoring for their Polarion installations. However,
this content should not be interpreted as "how-to" documentation for every Polarion installation. Rather,
it illustrates an approach that has proven effective for one product development team's installations,
in their specific environment. It does not attempt to cover the entire problem domain of performance
monitoring, and assumes familiarity with the third-party monitoring applications and use cases.
DISCLAIMER: Siemens Digital Industries Software does not recommend or endorse any third-party
software mentioned in these topics.
Polarion DevOps uses a PowerShell script ( Web_monitor.zip ) and Zabbix to gather performance
information by measuring user logon time. (It can also be done without using Zabbix.)
Prerequisites
A Microsoft Windows instance with the following: PowerShell 5, Zabbix agent and zabbix_sender.exe
(included in the zabbix-agent installation).
Note
All commands in the following client and server setup instructions are executed in PowerShell with
administrator privileges.
Procedure
3. Set the PowerShell location to where you unzipped the _Web_monitor.zip file.
<Set-Location_to_your_folder> sl c:\zabbix
4. Run the following command:
.\pw_tool.ps1 'C:\zabbix\secret.txt'
Fill in the User name and Password fields in the dialog box to log in to Polarion. The script generates
the password hash file in the indicated folder. Add the password hash file path to the configuration
part of the test_webpage_login.ps1 file.
5. Open the test_webpage_login.ps1 file using a PowerShell editor (for example with the Integrated
Scripting Environment (ISE)), and make changes to the setup of the webpages, monitoring
requirements, email setup, and Zabbix based on the environment of the customer.
Running the script in an infinite loop is good for testing purposes, but for production environment, it
is recommended to set up scheduled tasks.
Procedure
The following section describes how to search for critical errors of the Polarion coordinator.
Prerequisites
Procedure
Set up crontab to ensure that there's a symlink for the latest logfile:
Procedure
Prerequisites
• Zabbix server
• Administrative access to the Zabbix server.
Procedure
Set up crontab to ensure that there's a symlink for the latest logfile:
Procedure
Using Zabbix to monitor the Java virtual machine (JVM) gives you a good overview of what's happening in
Polarion and provides historical data for comparison.
Prerequisites:
Caution
The basic configuration below is for testing purposes only. (It allows anonymous, unsecured,
unrestricted access to your JMX.)
Note
To monitor JVM in a Cluster, you must set it up on all application nodes, including the Coordinator.
Procedure
1. Add the following configuration parameters into the PSVN_JServer_opt section of the config.sh or
polarion.ini files.
a. For Linux:
File location: /opt/polarion/etc/config.sh
-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.port=9010 \
-Dcom.sun.management.jmxremote.local.only=false \
-Dcom.sun.management.jmxremote.authenticate=false \
-Dcom.sun.management.jmxremote.ssl=false \
b. For Windows:
File location: [POLARION_HOME]\polarion\polarion.ini
-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=9010
-Dcom.sun.management.jmxremote.local.only=false
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
2. Restart Polarion.
3. Import the Template_JVM_Generic.xml template into Zabbix templates.
4. Link the JVM Generic template to hosts with Polarion.
5. Add the JMX interface on the Zabbix host configuration site.
6. Check the graphs and triggers that are generated
7. Check the latest data with Zabbix.
Additional JMX monitoring helps get an overview of what is going on with the JVM using historical data for
comparison. You can define what values you're interested in by adding custom values from MBeans.
Prerequisites:
Procedure
Polarion can expose license utilization statistics via Java Management Extensions (JMX) MBean.
Procedure
Prerequisites
Procedure
5. Check the generated items for the host. Search for items with the component: license tag.
The following steps are optional when using the Zabbix template:
Procedure
1. Get the metadata for MBeans. The ObjectName can be for example:
com.siemens.polarion:type=Statistics.License,Statistics=Concurrent,name=Va
riants Add-on.
An Elasticsearch, Logstash and Kibana (ELK) stack is a centralized log solution to collect, parse, visualize,
and store system logs systems.
Here we'll cover how to configure a multiline stack trace so that its log is contained in a single record log
with a single ID.
Prerequisites:
Procedure
1. The configuration example used in the following section of the filebeat.yml file (/etc/filebeat/
filebeat.yml) can be used to repeat all multiline Polarion logs.
paths:
- '/var/log/polarion/main/log4j-errors*.log'
multiline.pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}'
multiline.negate: true
multiline.match: after
fields:
tags: [ "polarion_errors" ]
filter {
if "polarion_errors" in [tags] {
grok {
patterns_dir => ["/etc/logstash/conf.d/patterns/patterns"]
match => { "message" =>"%{JAVACLASSER:java.class}" }
}
mutate {
Have Filebeat collect Data from the Polarion RPC csv log file
This log can help you analyze Polarion performance issues faster by isolating the problematic time period
and search for it in the TX Polarion logs.
Prerequisites:
Procedure
1. Add the following to the filebeat.yml file (/etc/filebeat/filebeat.yml) on the log source of the Polarion
server.
- paths:
- '/var/log/polarion/main/log4j-rpc-2*.csv'
fields:
tags: [ "polarion_rpc" ]
Note
Our DevOps have decided to use Logstash to collect data from the Polarion server but ingest could
be used on Elasticsearch directly.
4. The following example shows how to collect data from the CSV log using Logstash. It ensures that the
separating field that parsed values are converted to the numeric type, and the separated index name
is specified for searches.
File location: /etc/logstash/conf.d/Polarion-rpc_csv-filter.conf
filter {
if "polarion_rpc" in [tags] {
csv {
columns => ["Time_stamp", "Live_tread", "Time_spend",
"Activity"]
separator => ","
}
mutate {
add_field => {
"[@metadata][indexname]" => "latest_rpc"
}
convert => ["Time_spend", float]
}
}
}
• The Time_stamp, Live_tread, Time_spend and Activity separated fields and their values
should be visible in Kibana.
• When a time filter is not used for the index pattern for RPC logs, you can use filters for values in
Kibana and sort them.
5. You can use the Time_spend field to filter problematic sections.
This log helps you to better analyze Polarion performance issues where it's possible to isolate a problematic
time period to provide more detailed information.
Prerequisites:
Procedure
1. Add the following example to the /etc/filebeat/filebeat.yml file on the log source of the Polarion
server.
- paths:
- '/var/log/polarion/main/log4j-tx-2*.log'
multiline.pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}'
multiline.negate: true
multiline.match: after
fields:
tags: [ "polarion_tx" ]
filter {
if "latest_polarion_tx" in [tags] {
grok {
match => {
"message" => [
"Total: %{NUMBER:Total}"
]
}
}
mutate {
add_field => {
"[@metadata][indexname]" => "latest_tx"
}
remove_field => ["host"]
convert => ["Total", float]
}
}
}
The log for system load averages can help administrators analyze performance issues that are hard to
pinpoint — where it’s unclear if a slowdown was due to a suspected operation, or because the system
happened to be overloaded when the operation ran, for example
Note
This logging is only available for Linux. Here's why. The settings will not harm Windows environments,
but no load data will be collected.
Logging can be configured and customized via the following system properties:
com.siemens.polarion.systemload.loggingTimeInterval
com.siemens.polarion.systemload.minimalValueToLog
• Enter a double value that defines the point you want to start logging the system load average.
• The default value is 1.
Note
The value provided from the system load average is not a percentage of the CPU usage.
For example, with a CPU usage of 88.3, the system load average could be 43.
You can get some good information on the Linux stress tool at the following websites:
• https://www.tecmint.com/linux-cpu-load-stress-test-with-stress-ng-tool/
• https://linux.die.net/man/1/stress
Tip
If you'd like to learn more about Linux load averages, check out this informative blog post.
• A warning message is sent if the available free disk space is running low. By default, notifications are
sent when free disk space:
◦ is less than 5%
◦ is less than 1 GB
◦ less than 100 MB
The free disk space limit is configurable. See configure free space limit, below.
• If Java is not able to recover enough heap memory during garbage collection, conditions may indicate
that Polarion is running out of memory, and the administrator may want to increase the -Xmx setting in
polarion.ini (Windows) or etc/config.sh (Linux) and restart the server.
Therefore, a warning message is sent when Java heap space is less than 5%.
Caution
If Polarion installed as a service, as it is in the default Windows installation, you will also need to
uninstall then reinstall the service.
Procedure
The email address(s) for the recipient(s) of these notifications can be set
by specifying a comma-delimited list of email addresses in the system
property:com.polarion.platform.monitoring.notifications.receivers
It is not enough to simply set this property. Monitoring of system resources must be configured as well.
The following system properties should be set:
com.polarion.platform.monitoring.notifications.disabled=false
com.polarion.platform.monitoring.notifications.receivers=<valid@email>
Related Topics
Overview
Your Polarion server may host more than one license type — named and concurrent, for example. For
named user licenses, you need to specify the user IDs of all users who will utilize each named license. For
concurrent licenses, you may want to limit the number of users who can access the portal concurrently —
the maximum is controlled by the license, and/or you may want to define groups of concurrent users with
different limits. You may also wish to check the current usage of your licenses.
You can manage licenses and view current license usage in the Polarion portal, in Global
Administration only.
Tip
Looking to monitor license usage with your enterprise monitoring tool? Now you can.
Procedure
2. If you are not in the Administration interface after you log on, click the Administration link in the
Tool view of Navigation.
3. If you are in a project after you log on, click Global Administration at the top of the Navigation
panel.
Results
The License Assignment and Usage page opens, where you can view and manage licenses.
The page contains embedded Quick Help that provides detailed information on how to use the various
license management features.
If your organization has purchased new, or obtained updated licenses for your Polarion installation, you
can update the installation from the License Assignment and Usage page. Use the Reactivate Polarion
button to begin the process. You will be taken to the first page of the activation application, where you will
find instructions for activating your license or licenses, either online or offline.
A confirmation dialog box appears on each online activation, before the activation request is actually sent.
You must confirm that no running Polarion instance is activated by the License Key you are activating.
The License page provides a plain text editor in the License Assignment section, enabling you to edit the
underlying configuration file, and named users in the file system.
See the Quick Help section on the License Assignment and Usage administration page for more
information.
When you change any text in the online text editor, the Save button is enabled which saves changes made
to the configuration file in the portal.
• If a user is assigned a Named license in the users file, then they just use that license.
• If a user is assigned a Concurrent license in the users file, then they just use that license. If no
Concurrent slot is available, they cannot log on.
• If the user is not assigned a license in the users file, they use the default Concurrent license. If no
Concurrent slot is available, they cannot log on.
• Default license is specified via the defaultUserLicense directive in the users file.
• If not specified, then the default is the Concurrent license with the highest number of concurrent slots.
• If licenses have the same highest number, then the lowest level license with the same highest number
is assigned.
License levels from lowest to highest: Reviewer, Pro, Requirements, QA, ALM
• If all are zero, then no license is assigned.
Note
The license assignment configuration can be changed only once in 20 minutes.
The License Usage section of the page provides subsections that display statistics on how users are
currently consuming the licenses available on your Polarion system. The numbers are current as of the
moment you invoked the page. Refresh your browser to see any change.
For information about the usage details displayed on the page, see License Usage Reference.
Polarion can expose license utilization statistics via Java Management Extensions (JMX) MBean.
(You can then use Zabbix or other enterprise monitoring tools to view these statistics.)
Procedure
Tip
Set the property value to update statistics every five minutes (3000000 milliseconds) to avoid
slowdowns when Polarion checks for licenses.
2. You must then set the following Java Virtual Machine properties to connect the JMX MBean from your
monitoring tool.
• For Linux:
Set the following in the config.sh file:
File Location: /opt/polarion/etc/config.sh
-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.port=9010 \
-Dcom.sun.management.jmxremote.local.only=false \
-Dcom.sun.management.jmxremote.authenticate=false \
-Dcom.sun.management.jmxremote.ssl=false \
• For Windows:
Set the following in the polarion.ini file:
File Location: Polarion\polarion\polarion.ini
-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=9010
-Dcom.sun.management.jmxremote.local.only=false
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
Note
If you have a clustered server environment, perform this setup on the coordinator machine.
3. See your enterprise monitoring tool's JMX monitoring documentation to connect it.
(For Zabbix see Zabbix Documentation: 13 JMX monitoring)
Advanced administration
Issues around server memory allocation and Java virtual machine are covered in the Deployment and
Maintenance guide on Support Center.
• Windows Installation
• Linux Installation
• Cluster Installation (for users running Polarion on multiple physical and/or virtual servers with one or
more Polarion instances in the topography.)
Administrators of Windows installations should follow the recommendations in the section Adjusting
Server Memory Allocation in the Windows Installation guide.
Be sure to review the information in the section Java Virtual Machine Memory Limit in the installation
guide for your operating system.
Administrators of clustered server installations should note the recommendations in the installation
guide for the operating system on their servers, well as any relevant instruction in the Deployment and
Maintenance Guide.
The information in these documents can help avoid issues such as failure to start the Polarion service, and
Java Out of Memory (OOM) errors.
Tip
See the PostgreSQL configuration topic in the Deployment and maintenance guide for scaling and
optimization information.
Polarion includes the embedded PostgreSQL database to process complex queries more efficiently than is
possible with the Lucene query engine. By default the database table containing the enumeration options
is not populated because this data rarely needs to be obtained from the database. However there can
be times when the complete enumeration options definition is required in the database. (Like when the
database is the primary source of this data, for example, if you are building an external report on top of the
Polarion database using the The Business Intelligence and Reporting Tool (BIRT) extension.)
If this is the case, you may not only need to load the unique IDs stored with the objects, but also the names
of the enumeration options.
To populate the enumeration options table in the Polarion databases, set the following property in the
polarion.properties file:
com.polarion.platform.sql.populateEnumOptionsTable=true
Once this property is enabled, a job that populates the enumeration options table, in both the HEAD and
historical database, is automatically run after each reindex.
Unlike Work Items or LiveDocs, the enumeration options are not automatically updated in the database
table when there's a configuration change.
To ensure the consistency of the enum options table with the actual configuration, the Refresh Database
button triggers a job that resynchronizes a particular enumerations configuration to the database.
Note
You must set com.polarion.platform.sql.populateEnumOptionsTable= to true in the
polarion.properties file or the Refresh Database button is not visible.
You can schedule the polarion.jobs.refresh.enumeration job to run regularly as a part of your
system maintenance. When it is run without any additional parameters, all enumerations are refreshed. By
default, the polarion.jobs.refresh.enumeration job only starts once after a reindex.
Object-based Enumerations
Object-based enumerations are not populated in the enum table. If required, they must be collected from
other tables. For additional information, see History Indexing Job and User Impact.
If you have enough resources, you might consider bumping up the memory available for Polarion and
enabling the In-memory Object maps feature.
Administrators can enable In-memory Object Maps to reduce wait time by 95% when moving Work
Items to and from Documents. Doing so will increase the amount of RAM used, and the size of the
object-maps folder. RAM usage will vary, but will be about 3 times the size of the object-maps folder.
How it works
• It optimizes Object Map implementation to minimize disk access. It is based on a map kept in memory
and saved to disk asynchronously.
• Saves are made each time the map is asked to do so, provided no additional save requests have been
made for ten seconds.
• While saving, all data is flushed onto the disk, and data in memory can still be modified.
To enable In-memory Object Maps, set the following property in the polarion.properties file:
com.siemens.polarion.persistence.objectMaps.inMemory=true. If the line is not already
present in the file, add it on a new line.
Warning
• The default value of this property is false. Whenever the value of this property is changed, it is
necessary restart the server and also to reindex the system.
• When this property is enabled (true), reindexing is also required if Polarion is ever shut down
abnormally.
On some production systems, depending on the configuration, the Object Map folder can get quite large
(10+ gigabytes).
A Defragment object maps job can be run that greatly reduces the size of this folder.
Warning
Set it to run during off-hours:
Some resources might be temporarily locked while the defragmentation job is run. To ensure that users
are not affected, run the Defragment object maps job over night on production systems.
The sample script above will run the Defragment object maps job everyday at six o'clock a.m. (06:00).
Polarion includes the embedded PostgreSQL database to process complex queries more efficiently than is
possible with the Lucene query engine. There may be times when an administrator needs to start, stop, or
restart the database.
On Windows, shortcuts are provided in the folder [POLARION_HOME]\polarion shortcuts. On Linux, the
following scripts are available:
Your Polarion server may host more than one license type — named and concurrent, for example. For
named user licenses, you need to specify the user IDs of all users who will utilize each named license. For
concurrent licenses, you may want to limit the number of users who can access the portal concurrently —
the maximum is controlled by the license, and/or you may want to define groups of concurrent users with
different limits. You may also wish to check the current usage of your licenses.
You can manage licenses and view current license usage in the Polarion portal, in Global
Administration only.
Tip
Looking to monitor license usage with your enterprise monitoring tool? Now you can.
Procedure
2. If you are not in the Administration interface after you log on, click the Administration link in the
Tool view of Navigation.
3. If you are in a project after you log on, click Global Administration at the top of the Navigation
panel.
Results
The License Assignment and Usage page opens, where you can view and manage licenses.
The page contains embedded Quick Help that provides detailed information on how to use the various
license management features.
If your organization has purchased new, or obtained updated licenses for your Polarion installation, you
can update the installation from the License Assignment and Usage page. Use the Reactivate Polarion
button to begin the process. You will be taken to the first page of the activation application, where you will
find instructions for activating your license or licenses, either online or offline.
A confirmation dialog box appears on each online activation, before the activation request is actually sent.
You must confirm that no running Polarion instance is activated by the License Key you are activating.
The License page provides a plain text editor in the License Assignment section, enabling you to edit the
underlying configuration file, and named users in the file system.
See the Quick Help section on the License Assignment and Usage administration page for more
information.
When you change any text in the online text editor, the Save button is enabled which saves changes made
to the configuration file in the portal.
• If a user is assigned a Named license in the users file, then they just use that license.
• If a user is assigned a Concurrent license in the users file, then they just use that license. If no
Concurrent slot is available, they cannot log on.
• If the user is not assigned a license in the users file, they use the default Concurrent license. If no
Concurrent slot is available, they cannot log on.
• Default license is specified via the defaultUserLicense directive in the users file.
• If not specified, then the default is the Concurrent license with the highest number of concurrent slots.
• If licenses have the same highest number, then the lowest level license with the same highest number
is assigned.
License levels from lowest to highest: Reviewer, Pro, Requirements, QA, ALM
• If all are zero, then no license is assigned.
Note
The license assignment configuration can be changed only once in 20 minutes.
The License Usage section of the page provides subsections that display statistics on how users are
currently consuming the licenses available on your Polarion system. The numbers are current as of the
moment you invoked the page. Refresh your browser to see any change.
For information about the usage details displayed on the page, see License Usage Reference.
Polarion can expose license utilization statistics via Java Management Extensions (JMX) MBean.
(You can then use Zabbix or other enterprise monitoring tools to view these statistics.)
Procedure
Tip
Set the property value to update statistics every five minutes (3000000 milliseconds) to avoid
slowdowns when Polarion checks for licenses.
2. You must then set the following Java Virtual Machine properties to connect the JMX MBean from your
monitoring tool.
• For Linux:
Set the following in the config.sh file:
File Location: /opt/polarion/etc/config.sh
-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.port=9010 \
-Dcom.sun.management.jmxremote.local.only=false \
-Dcom.sun.management.jmxremote.authenticate=false \
-Dcom.sun.management.jmxremote.ssl=false \
• For Windows:
Set the following in the polarion.ini file:
File Location: Polarion\polarion\polarion.ini
-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=9010
-Dcom.sun.management.jmxremote.local.only=false
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
Note
If you have a clustered server environment, perform this setup on the coordinator machine.
3. See your enterprise monitoring tool's JMX monitoring documentation to connect it.
(For Zabbix see Zabbix Documentation: 13 JMX monitoring)
If some Excel Import Configurations become disused or obsolete over time, they can be removed using
the Repository Browser. Import configuration may be saved the global/repository scope or in the scope of
some project. Deleting an Excel Import Configuration does not require administrator permissions, but the
user performing the removal must have permissions to delete content from the repository in the relevant
scope.
Procedure
Tip
If the excel directory is not present, then there are no Excel Import Configurations saved in the
current scope.
4. Select the check box on the row of each import configuration you want to delete.
Warning
There is no Undo available, so be sure you are deleting what you want deleted.
Results
The selected Excel Import Configurations are deleted from the repository.
What to do next
Note
By default, there are also repository folders containing import configurations for Microsoft Word (folder
word) and Microsoft Project (folder msproject). Import configuration files in these folders can be
deleted in the same way. However, it is recommended that you only delete user-created configuration
files and keep the default ones so they can be reused as templates for any future custom import
configurations.
The Dashboard topic is implemented as a Classic Wiki page. You can customize the layout and content
of this page using the macros discussed in this section. Details on macro syntax are provided in the
embedded Wiki Syntax Help, accessible when editing the page. Both administrators and users with read
and write permissions for Classic Wiki pages can edit the page.
Procedure
Note
If the topic does not appear In Navigation, it has been hidden in the global and/or the project
configuration. Administrators can show or hide Navigation topics in Administration
Portal Topics.
You can organize the content of the dashboard into table and or column structures using these macros:
Again, please refer to embedded syntax help for syntax and usage examples of these macros.
There are several macros which roll up and display information from the system in the Dashboard. The
most important ones are:
{fact} Renders some useful values from Polarion's factbase. These values are stored
for example in the workitems-data.xml file under the data folder of the Polarion
installation. For example, the file for the repository scope is stored in xml/workitems-
data.xml, located in directory [POLARION DATA]/RR/default/.reports/xml/ (Linux) or
[POLARION DATA]\RR\default\.reports\xml\ (Windows).
This XML file contains computed values that can be rendered as numbers or graphs:
UNRESOLVED-BY-ASSIGNEE, OPEN-BY-SEVERITY, STATUS and so on. Values are
populated by reports (see Configure Reports).
{linechart}, These macros render information from HTML and XML files generated automatically
{piechart}, by system calculations. The main thing you need to understand about them is that
{report} the path in their report-path is a relative path in the PR directory. For example, if a
macro is executed in project elibrary, then the path is relative to the reports for that
project.
For reference information about factbases and values see Calculations and Facts.
There is a calculation named all that calculates all metrics, charts, and reports in a given scope. The default
system configuration has a job named All Calculations that invokes this calculation. Schedule or call this
job if you want to be sure that everything is freshly calculated.
Each section of the Dashboard contains an Update button which can be used to recalculate and refresh
specific information displayed in the Dashboard.
Depending on what you have configured to appear in the Dashboard, you may only need run some
calculations, as opposed to all calculations as described above. You should configure the specific reports
that run the calculations for the data you are displaying in the Dashboard. For information, see: Work with
Report Configurations.
Excel export templates enable you to set up different export scenarios for users of the Excel round-trip
features. Templates specify which Work Item fields are exported for round-trip, and the default type for
new Work Items created via Excel round trip.
Several export templates used for exporting Work Items to Microsoft Excel format are provided in the xlsx:
Microsoft Excel section of the Export Templates topic of Administration.
Best practice for creating your own Excel export templates is to derive new ones from Polarion's default
export templates.
The following sections discuss the characteristics of an Excel export template, and describe several
common customizations.
Basic.xlsx Template with some basic column-to-field mapping. A good starting point for many
customizations.
Empty.xslx Contains the required tables (describe later), but nothing else. No columns are defined
in the template sheet, and there is no default column-to-field mapping. If used for
round-trip export, the export dialog fields selection is prefilled with all columns that are
shown in the Table view of Work Items.
Tip
This template is best used as the basis for new templates not derived from or based
on any other.
TimeReport.xlsx This template defines a work time report. It serves as a good example of how to define
calculated columns in your custom Excel export templates.
Start by downloading the Excel export templates and checking to see how much is already implemented
that you can use. The Empty.xlsx template is the most basic template with minimal data. The Basic.xlsx
template has some typically used fields and columns predefined. The Time Report.xlsx template has some
examples of calculated columns. Create a copy of one of these export templates and customize it to suite
your needs.
Work Items are exported to a named region of the worksheet, called an Excel table, named WorkItems.
Your template must contain this table, which should contain only a header and one normal row — the
template row (see figure below). In Polarion's default export templates, this table is found in Sheet 1. Any
column in this template sheet that has the a column label corresponding to a Polarion Work Item field ID
is automatically mapped to the corresponding field. This includes custom fields. You can add columns as
needed. If you need to have column names that do not correspond to field IDs, use the mapping table on
the Polarion sheet.
The default Excel export templates also contain a hidden sheet named Polarion. This sheet specifies
some settings for the exporter and enables column to field mapping when template column names do
not correspond to Polarion Work Item field names. Your custom template should contain this sheet with
the two tables from Polarion's default templates. You will need to manually show this hidden sheet in
the workbook if you need to make changes to it, and then change it back to the hidden state before
distributing your custom template.
The first table in the Polarion sheet is a table of property-value pairs that enable you to set default values
for two properties:
New Work Item Type Specify the type for any new Work Items that may be specified by end users in
exported round-trip workbooks based on the template, and created in Polarion
during re-import.
New Comments A regular expression value that matches headers of columns that should be
Column imported as new Work Item comments.
The second table on the Polarion sheet is a column-to-field mapping table. Use this table to map any
columns in the template table of Sheet 1 whose column names do not correspond to Polarion field names.
Each row corresponds to a column in Sheet 1 that doesn't have a column name matching a field ID. If
there are rows in this table that duplicate the mapping on Sheet 1, then you don't need to remove them.
The mapping will not be duplicated.
When adding a new column and field row to the mapping table, be sure to use the Insert context menu on
a row in the mapping table. Do not add rows outside the table. Rows inside the table will be shaded.
If you should happen to specify a field that doesn't exist, it will not appear to users in the Export Work
Items dialog box when they select the Excel option when exporting Work Items.
The end result of your customized template, when uploaded to the portal, should be that all fields you
have mapped in the template appear to users as the default fields in the Selected Columns list of the
Export Work Items dialog. It's recommended that you save your templates with different file names from
the default templates. You can upload your finished templates to the Export Templates page (described
earlier) of Administration, and then test them by invoking Export in the Table view of Work Items,
and selecting xlsx: Microsoft Excel in the Format field. If you need to modify your template for any
reason, you can do so and upload it again using the Replace existing export template with this upload
option.
Add a column
Procedure
1. Open the sheet of the export template containing the WorkItems region (normally on Sheet1).
2. On first row after the header row (the template row referred to earlier), drag the lower right corner
of the right-most cell until you see the outline for a new column, or use the content menu of the
right-most cell to insert a column to the right.
3. Set the value of the new column's header to the name of a Work Item field to which you want the
column mapped.
Alternatively, set the header value to any unique value, and then on the Polarion sheet add a row to
the mapping table.
Procedure
1. Create a new column as described in the previous section, but do not map it to any field. Rather,
specify a unique value in the column header.
2. Enter the desired formula in the template row cell of the new calculated column.
Tip
You cannot use relative cell references. Rather you should use table column references. For
example: =[Time Spent]+[Remaining Est.]-[Initial Est.]
The calculated columns in the default Time Report.xlsx export template can provide a useful
example of such references.
Procedure
1. Open the sheet of the export template containing the Work Item region (normally found on Sheet1).
2. In the first row after the header row (the template row referred to earlier), select the cell you want to
make read-only.
3. Right-click on the cell and select Format Cells from the context menu.
4. Select the Protection tab.
5. Check Locked and click OK.
Excel export for offline testing of Test Cases supports the export of Test Cases with multiple Iterations of
Test Steps. By default, the export template is configured to append a label for each Iteration to the Title
column in the exported workbook. It is possible to configure which field displays the Iteration number in
the property Append Iteration Label to Field in the hidden Polarion sheet. The default is the Title field.
Tip
See Configure Test Export Templates for more information.
Limitations
The sheet size of a Microsoft Excel template is limited by two properties in the polarion.properties file:
You can increase these limits if needed, but the export might take a long time and consume a high amount
of memory.
Work Items can be exported to XML. Export is accomplished by means of XSL templates (XSLT). You can
create your own XSL templates to transform exported Work Items to another XML document, a HTML
document, a plain text file, PDF, or RTF. When creating your own XSLT, refer to the Polarion XML Export
Schema.
Administrators can access the templates in global or project scope by opening Administration
Work Items Export Templates xml:XML Export.
You can also use the integrated Repository Browser to access export templates. Templates are located on
repository path /.polarion/tracker/export_templates/. You must use this tool to access the XSL templates.
Each of the exporters has a unique set of templates. Which template is used for which exporter is
determined by the name of the template:
Upload your custom XML export templates to the repository folder .polarion/tracker/export_templates.
It is possible to import Microsoft Word documents that contain OLE objects. Polarion can display OLE
Object thumbnails during Word document import. However, some additional third-party image converter
software must be installed and configured before you can import such Word documents. OLE Objects in
documents must contain their thumbnails in .emf or .wmf file formats, and the image converter used
must support their conversion into JPEG. OLE Objects themselves are not imported, only their thumbnails.
Installation of third-party image converter, and configuration of Polarion to support OLE objects are
covered in the Polarion Deployment and Maintenance Guide, available on Support Center.
You can customize the Polarion user interface by injecting HTML and JavaScript snippets into Polarion's
HTML pages.
A set of properties enables the injection of custom code into the logon screen, Polarion portal or the
Document Editor:
Tip
See the Polarion Extensions Portal for more information and code examples.
The custom code can be either inserted via the following properties in the polarion.properties file, which
can alter the <head> or <body> tag of the logon or main pages of Polarion.
• com.siemens.polarion.scriptInjection.loginHead
• com.siemens.polarion.scriptInjection.loginBody
• com.siemens.polarion.scriptInjection.mainHead
• com.siemens.polarion.scriptInjection.mainBody
Customize the <Head> of Polarion's Document Editor and its Print Preview screen.
• com.siemens.polarion.scriptInjection.dleEditorHead
• com.siemens.polarion.scriptInjection.dleEditorHead
Alternatively, you can insert the custom code via the following runtime Configuration Properties in
Polarion Global Administration.
Leveraging the configuration via Polarion administration lets you modify the injected HTML content
without having to restart Polarion to apply the changes.
Note
These configuration properties can be only used on the global level of Configuration Properties.
(If you add them to Configuration Properties on the project level, they are ignored.)
• scriptInjection.loginHead
• scriptInjection.loginBody
• scriptInjection.mainHead
• scriptInjection.mainBody
Customize the <Head> of Polarion's Document Editor and its Print Preview screen.
• scriptInjection.dleEditorHead
• scriptInjection.dlePrintHead
These code snippets can be used for many different purposes including, but not limited to:
• Integrate a custom analytics engine into the Polarion UI to monitor the usage of a specific Polarion
instance.
• Augment the Polarion UI with an onboarding solution that guides end users through your process
workflow.
• Display notifications about planned Polarion maintenance on the logon screen and in the Polarion
portal.
• Add custom buttons to the Polarion user interface.
• Hide controls for some of Polarion's out-of-the-box features and functions.
Caution
• Polarion support does not provide help with implementing specific Polarion UI customizations. Refer
to the Polarion community portal with your questions.
• Adding custom JavaScripts into the Polarion UI may have performance and functional implications, so
keep that in mind when implementing this kind of customization.
• Polarion CSS styles and HTML elements are not API, so they can be subject to changes between
releases and even patches.
• HTML injector is a generic and powerful tool for customizing Polarion, which can have unforeseen
consequences if not implemented correctly.
Administrators leveraging this customization option must accept responsibility for the script content
and understand the related risk.
Only deploy scripts you understand from a functional, performance, security and an end-user impact
point of view.
You can customize Polarion's login page by adding your company's logo, server icons and more.
Available customizations
Replace the Siemens logo on the Login Disable the "Stay logged in" option.
page.
Change the internal Login dialog box size.
Add custom server logos.
You can replace the Siemens logo on the Login page with your own.
Procedure
Example
• login.companylogo=http://your_url.com/[IMAGE] or
login.companylogo=https://your_url.com/[IMAGE]
(If you have it at an accessible internet location.)
• login.companylogo=https://$[base.url]/[IMAGE]
(If you placed it in Polarion's Apache folder.)
(The Polarion server must be able to access it via the HTTP(S) protocols.)
(For a Clustered setup: Stop all Nodes Restart the Coordinator Restart all Nodes.)
You can add your own server icons to the Polarion Login screen and Navigation Header.
Tip
If you are running a Multi instance setup, you configure different server icons for each server instance so
your users can quickly know which one to select.
2. Decide where you want to host your server logo and place it there.
a. You can store it online at an accessible HTTP/HTTPS address.
Tip
If you are running a Multi instance setup, you configure different server icons for each server
instance so your users can quickly know which one to select.
Tip
For a Multi instance setup, copy and reference your images to an online location so that they
are always available, even during maintenance.
(Not in the instances' Apache folders.)
Note
In a Clustered environment, after updating the polarion.properties file on the Shared Services
machine, you must restart the entire Cluster.
a. Stop all Polarion Nodes.
b. Restart the Coordinator.
c. Restart all Nodes.
You can disable the Stay logged in option for users on the login page.
By default, if users select Stay logged in on the main Login page or the internal Login popup window,
they are automatically logged on the next time they use Polarion without filling in their credentials.
To remove the Stay logged in option from the Login page, set the following property to false in the
polarion.properties file.
com.siemens.polarion.security.rememberMe.enabled=false
If set to false, the Stay logged in option does not appear on the main Login screen or the internal Login
popup window. Users who previously selected Stay logged in must also enter their credentials each time
they log on to Polarion.
The Repository Browser uses the following information to detect if a file is binary or text: the svn:mime-
type property, the container (Tomcat) mime-type settings, and context parameters BinaryMimeTypes
Tip
n.nn.n in the path above are numbers specifying a Polarion version number — 3.19.1, for example.
If MIME type is detected in SVN properties or container settings, it is then looked up in the
BinaryMimeTypes and TextMimeTypes context parameter elements. If the MIME type isn't set, or
isn't present in those lists, then an automatic algorithm is used, which analyzes the first 1000 bytes of the
file and returns the best guess as to the file type.
This approach still cannot guarantee 100% accuracy of file type reporting and file handing in the
Repository Browser. For example, one organization might want to have a file type .xyz treated as binary,
while another wants the same file type interpreted as text. If you find that some file types are not reported
and handled correctly in the Repository Browser, or if you have some file types that you want to make
sure are always interpreted correctly, you can edit the web.xml file, setting MIME-type mappings and
interpretations in the BinaryMimeTypes and TextMimeTypes context parameters.
Thread dumps
A thread dump captures the state of all Java threads in the system and provides crucial information to
troubleshoot performance issues.
Administrators can manually trigger a thread dump on the Maintenance page of Administration, in
either global or project scope.
The thread dump is then written to the Polarion log files, that you can send to Polarion technical support
if necessary.
Tip
The most convenient method is to enable JMX remote access and use the VisualVM interface to
connect to the JVM to make the thread dumps.
If you do not have JMX connection enabled and the UI is not accessible, you can collect thread dumps
manually.
You can use the jcmd utility in the Java Development Kit (JDK). If you run Polarion with Java Runtime
Environment (JRE) instead, then please install JDK in the same version as the JRE you are using.
Tip
See the Java Flight Recorder (JFR) from the UI and Jave Flight Recorder (JFR) manually from a command
linetopics in the Deployment and maintenance guide.
attachments.indexingOfAttachmentContent.enabled
When not present in polarion.properties, or if added to the properties file and set to true or head (the
default), indexing of the content of attachments is enabled. When enabled, attachments for Documents,
Pages, Work Items, and Test Runs are indexed.
Examples:
• attachments.indexingOfAttachmentContent.enabled=head
Setting this property to "head" (the default) only enables the indexing of attachment content in the
head index.
• attachments.indexingOfAttachmentContent.enabled=false
Setting this property to “false” disables the indexing of attachment content. (Can improve indexing
time.)
Note
If you set this value to "false", the content of attachments can no longer be searched.
Other attachment fields (author, title, fileName, updated and length) are not affected by this
property, are always indexed, and are therefore searchable by users.
• attachments.indexingOfAttachmentContent.enabled=true
Setting this property to "true" enables the indexing of attachment content in both the head and
history indexes.
The attachments index can be explicitly refreshed via the Maintenance page in Administration.
Attachment indexing is performed by a background job when the server is started. Users may not be able
to search attachments for some time until the indexing job is completed.
For a list of supported attachment file types, see Working with Attachments.
attachments.indexingOfAttachmentContent.additionalFileTypes
Specifies file type extensions of attachments whose content is to be indexed in addition to Polarion's
default set of attachment file types.
The string of file extensions should be separated by a comma, and the extensions must not include the
period (.) character. Wildcards are not supported.
Example:
attachments.indexingOfAttachmentContent.additionalFileTypes=csv,xls,xlm
See Working with Attachments for the list of default attachment file types that are included.
attachments.indexingOfAttachmentContent.fileTypesToIgnore
Specifies the file type extensions of attachments whose content is to be ignored when Polarion indexes
attachments. Types specified can include any from Polarion's default types that you don't want indexed for
content, as well as other types.
The string of file extensions should be separated by a comma, and the extensions must not include the
period (.) character. Wildcards are not supported.
Example: attachments.indexingOfAttachmentContent.fileTypesToIgnore=doc,java,pdf
Note
A set of default attachment extensions is already enabled in Polarion, but if any are unnecessary, or are
causing issues, you can exclude them with this property.
attachments.maxSizeOfIndexedAttachmentInMB
The value can be either an integer value (file sizes of 1 MB or more), or a float value. If no value
is provided, or the property is left out of the properties file, a default value of 50 MB will be used
if attachments.indexingOfAttachmentContent.enabled is set to true. The default limit of
50 MB has been found generally suitable for Polarion installations meeting the recommended system
requirements
The setting applies to all attachments to any content that supports them: Documents, Pages, Work Items,
Test Runs, etc. The limit also applies to imported documents. If users encounter Out of Memory errors
when uploading attachments or importing documents, check the limit in this configuration setting, and
either adjust the setting, or add more system memory and storage, as needed to meet the needs of your
users.
Examples:
• attachments.maxSizeOfIndexedAttachmentInMB=2
• attachments.maxSizeOfIndexedAttachmentInMB=0.5 (512 KB)
• attachments.maxSizeOfIndexedAttachmentInMB=5.5 (5.5 MB)
maxAttachmentSize
Controls the size of any attachment in Polarion. If the attached file is bigger than the configurable limit, the
upload is stopped.
It applies to Work Item, Wiki Document, Live Document and imported document attachments.
collections.showOutOfCollectionLinks
Controls whether to show Work Item links and backlinks in the Collection context, even when they point
to/from Work Items outside of the Collection.
When set to true, links and backlinks are shown. When set to false, they are hidden.
com.polarion.durationHoursPerDay
Specifies the number of hours per work day. Requires an integer value (default value is "8"). Other
type values are silently ignored and the default substituted. The setting applies globally and cannot be
overridden in the project or project group scopes. The specified value appears read-only in the Work Items:
Planning page of Administration.
com.polarion.enumerations.objectEnumerationsLimit
Sets a hard limit on the number of items that are loaded into enumerated lists of system objects such as
Documents, Pages, Test Runs, users, etc. Excess items cannot be selected in the UI. Default value is 10 000.
You can set a whole number (for example, 200 ), or -1 for unlimited.
Take for example a custom field in which users select a Document from a drop-down list of Documents
(provided by an object enumeration). If the system contains hundreds or thousands of Documents,
populating the select list can take too long. Setting a lower limit in this property can significantly improve
performance.
com.siemens.polarion.ui.nameIdAutoFilling.enabled
It enables/disables auto-filling for the Name (ID) field in Polarion dialog boxes like the following:
com.polarion.ui.maxRenderedItemsInGroupsDialogs
Defines the maximum number of items shown in the Add Users, Add Global Roles and Add Project
Roles dialog boxes when creating and managing User Groups. (It's set to 100 by default and applies to all
dialogues on the Groups page.)
Caution
Setting a value significantly higher than the default can negatively affect performance and lead to long
data loading times.
If there are fewer Users in the system than the value set in the property, a message displaying the total
number of Users appears under the list.
If there are more Users in the system than the value set in the property, Users are informed about it and
are advised to use the filter to refine their results.
polarion.startup.disable.artifacts.auto.recognition
• Controls whether or not build artifacts auto-recognition during startup should be disabled (affects only
projects where there are no configured build artifacts and auto-recognition is not disabled on the project
level).
polarion.startup.disable.artifacts.change.detection
• Controls whether or not detection of build artifacts-related changes should be disabled during startup
(does not affect first startup or reindex or projects created while the server was not running).
• Default value: true.
• Setting the value to true will result in significant speed-up of restart.
com.polarion.ui.maxRenderedItemsInCombo
Universally controls the number of items loaded into combo box lists. Default value is 100. Decreasing the
value can improve loading of lists, if performance is noticed to be slower than optimal, which may occur
if there are many projects with many concurrent users. Users can filter for excess items by typing a string
of characters in the combo box. For example, assuming an item "Zebra Stripe Pattern", user can filter by
typing zebra.
useDecimalHoursDurationFormat
• Controls whether or not the value for hours in time reporting fields (Initial Estimate, Time Spent, etc.)
must be entered as a decimal value rather than the default fractional.
• Default value: false.
• When set to true, hour durations in all time reporting fields are displayed and entered as decimal hours
only - 22.33 for example. The examples displayed by clicking on the "?" next to time input fields are
changed when this feature is enabled, and the export option Convert Durations to decimal
hours is not displayed in the export dialog.
Storage in XML persistence and pre-2011 LiveDocs is still in the fractional format, only hours are not
converted to days. So the value in the example above is actually stored as 22 1/3h. It is stored that
way rather than 22 33/100h because of smart parsing of user-entered values to the fractional format,
which recognizes the decimal representation of fractions (y/3, y/6 and y/12). So for example entering
0.08 or 0.083 is parsed as 1/12h. The smart parsing can be disabled by setting the system property
dontUseSmartDecimalHoursDurationFormatParsing to true.
wordImport.ignore.[CLASS]
Where [CLASS] the short name of an object class from the docx4j library
• Controls whether or not unsupported content, of the type represented by the specified class, is reported
with the Unsupported Content message (see screenshot) in the result Document after importing a
document from Microsoft Word.
By default, unsupported content contained in the import source is not imported, and is replaced by the
graphical message shown below in the result Document after the import process finishes. If you would
rather that such content be silently ignored, you can add this property for each type of unsupported
content you do not want reported in the import result Document.
Graphical message when an object in a source document cannot be imported to Polarion. Set this property
to suppress it.
Example:
wordImport.ignore.R.DayLong=true where R.DayLong is the short name of the class of the object
from docx4j library.
In this case, content objects of the R.DayLong class will be ignored during import and no message will
appear in the import result. To find the class name, look at the tool-tip on the Unsupported Content
message in an import result where some unsupported content was present in the source document.
Note
OLE thumbnails are supported for imported Word documents when third-party image converter software
is installed and configured. See Documents with OLE Objects for more information.
com.polarion.logoURL
Optionally specifies the URL of a remotely hosted logo or icon image to display in the Navigation panel in
lieu of the default logo. The hosted location must be accessible to the Polarion server. If this property is not
specified, the default logo is displayed.
If specified, the remote image should ideally be 60 W x 64 H (pixels) in GIF, PNG, or JPG format.
Larger images should ideally have the same aspect ratio,and will automatically be resized and cropped
if necessary to fit the display space allocated by Polarion in the Navigation Header.
This can especially useful for organizations running multiple Polarion servers. A different logo image can
be configured for each server, enabling end users to tell at a glance which one they are connected to.
Example:
com.polarion.logoURL=http://myhost.myorg.com/images/server1_logo.png
com.polarion.ui.lock.timeout
Optionally specifies a lock timeout in minutes for the Diagram Editor. When a user begins editing a
diagram, a lock is set and no other user can edit it until the diagram changes are saved, the user closes the
Diagram Editor, or the lock timeout set in this property occurs.
If this property is not specified, the lock timeout defaults to 8 hours. The user who obtained the lock must
save the diagram or close the Diagram Editor in order to remove the lock.
Example:
com.siemens.polarion.repository.git.timeout
Administrators can set a Repository Polling timeout value for when changes are pulled from an external Git
repository.
If this property is not specified, the default timeout for Repository Polling job is set to 30000ms (30s)
Example:
com.polarion.ui.login.resetPasswordLinkURL
Holds the URL of a page on your system that you have provided for users to reset their password. You must
also set the resetPasswordLinkLabel property (below).
Example:
com.polarion.ui.login.resetPasswordLinkURL=http://www.mydomain.com/user/
recoverpw.php
com.polarion.ui.login.resetPasswordLinkLabel
Link text to display on the Polarion portal login page, leading to your password reset page. You must also
set the resetPasswordLinkURL property (above).
Example:
com.polarion.ui.login.resetPasswordLinkLabel=Reset Password
com.siemens.polarion.ui.linkedRevisions.renderingLimit
Sets the maximum number of Linked Revisions shown on the Work Item Properties sidebar.
Default value: 20
Example:
com.siemens.polarion.ui.linkedRevisions.renderingLimit=20
• This property does not affect how many Linked Revisions will be loaded when viewing the Work
Item itself.
(It's only for what Linked Revisions appear in the Work Item Properties sidebar.)
• If the number of Linked Revisions is higher than this limit, then a Show more link appears.
When Show more is clicked, users will be directed to the Work Item where all Linked Revisions are
visible in the Linked Revisions extension.
The AJP connector is deployed automatically, but you can specify the ajp-port in the
polarion.properties file by adding the following line:
TomcatService.ajp13-port=8889
Configuration steps
Procedure
Results
This will deploy Polarion directly on the HTTP protocol on port 80.
Apache Lucene query results are restricted to artifacts from the Projects that the user making the query
has permissions for.
This restriction is enabled by default and can be disabled by setting the following property to false in the
in the polarion.properties file:
com.siemens.polarion.security.searchDisclosedProjectsOnly
Apache Lucene only searches for and returns results for the Projects assigned to the user doing the
query.
(They do not see results they do not have permission to view.)
• When set to false:
Apache Lucene queries return ALL found objects.
Polarion then applies its permission check after the query is resolved.
Users see "You cannot see this object" messages in the artifacts they do not have permission to
view.
com.siemens.polarion.security.searchDisclosedProjectsOnlyQueryBy
• Stick with the default options if you have less than 1000 Projects and users.
com.siemens.polarion.security.searchDisclosedProjectsOnly=true
com.siemens.polarion.security.searchDisclosedProjectsOnlyQueryBy=forbidden
• If most of your non-admin users have more allowed projects than forbidden, you should also stick with
the default forbidden option.
• If most of your non-admin users have more forbidden projects than allowed, you should use allowed.
Note
Forbidden / allowed Projects are based on the following permission:
com.polarion.persistence.object.Project.read
Tip
Still not sure what settings to use?
Add a script widget containing the velocity code below in a LiveReport Page before updating
Polarion.
It will provide some insights on what setting is best for your Polarion deployment.
##start
#set( $perm_project_view="com.polarion.persistence.object.Project.read" )
#set( $perm_project=$securityService.constructPermission($perm_project_view)
)
Permission object: $perm_project<br>
#set ( $allUsers = $projectService.getUsers() )
All users size: $allUsers.size()<br>
#set ( $allProjects = $
$projectService.getRootProjectGroup().getDeepContainedProjects() )
all projects size: $allProjects.size()<br>
<br>Summary is at the bottom of the page<br><br>
#set( $permissionCountAllowed = 0 )
#set( $permissionCountForbidden = 0 )
#set( $permissionCountAllChecks = 0 )
#set( $maxAllowed = 0 )
#set( $maxForbidden = 0 )
#foreach( $user in $allUsers )
#set( $userAllowed = 0 )
#set( $userForbidden = 0 )
#foreach( $project in $allProjects )
#set( $permbool = $securityService.hasPermission($user.getId(),
$perm_project, $project.getContextId()) )
#if( $permbool )
#set( $permissionCountAllowed = $permissionCountAllowed + 1 )
#set( $userAllowed = $userAllowed + 1)
#else
#set( $permissionCountForbidden = $permissionCountForbidden +
1 )
#set( $userForbidden = $userForbidden + 1 )
#end
#set( $permissionCountAllChecks = $permissionCountAllChecks + 1 )
#end
allowed: $userAllowed , forbidden: $userForbidden, user:
$user.getId()
#if( $userAllowed > $maxAllowed )
#set( $maxAllowed = $userAllowed )
#end
#if( $userForbidden > $maxForbidden )
#set( $maxForbidden = $userForbidden )
#end<br>
#end<br>
The log for system load averages can help administrators analyze performance issues that are hard to
pinpoint — where it’s unclear if a slowdown was due to a suspected operation, or because the system
happened to be overloaded when the operation ran, for example
Note
This logging is only available for Linux. Here's why. The settings will not harm Windows environments,
but no load data will be collected.
Logging can be configured and customized via the following system properties:
com.siemens.polarion.systemload.loggingTimeInterval
com.siemens.polarion.systemload.minimalValueToLog
• Enter a double value that defines the point you want to start logging the system load average.
• The default value is 1.
Note
The value provided from the system load average is not a percentage of the CPU usage.
For example, with a CPU usage of 88.3, the system load average could be 43.
You can get some good information on the Linux stress tool at the following websites:
• https://www.tecmint.com/linux-cpu-load-stress-test-with-stress-ng-tool/
• https://linux.die.net/man/1/stress
Tip
If you'd like to learn more about Linux load averages, check out this informative blog post.
Administrators can configure history limits (number of days and maximum number of items) for each
Activity source, plus a default registered activity source, via the system properties listed in this topic.
Specific source
In the Tree view of Work Items, some user queries can return a tree so large that the performance
of the entire system is adversely affected. Before constructing a tree of Work Items, Polarion checks two
system properties with default values designed to prevent this. However, administrators can review and
optionally adjust these properties depending on their system's resources.
com.polarion.ui.treeTable.softLimit
The check is performed on the number of items returned by the query. If the count exceeds the limit, the
user is informed that the tree is large, it can take a long time to load, and the message asks permission
to display only the top N nodes (where N is the limit set in this property). These top items can be on any
level of the tree. This is neither the final number of nodes, nor the final number of roots. Rather, it is the
initial number of roots. When the tree is created some of these items might be removed and others might
be added.
com.polarion.ui.treeTable.hardLimit
If the user rejects loading of the top N items, a second condition is checked in this, property. The default
value is 10000. If the total number of nodes returned does not exceed this limit, the tree is constructed
from the full query result. Otherwise, the user is shown a message that the tree is too large to show and
has been limited to N nodes, where N is the value set in this property. Again, the administrator can set a
higher or lower limit.
Matrix rendering
There are two system properties that define the maximum number of cells in a Traceability matrix or a
Variants comparison matrix.
com.siemens.polarion.ui.matrix.hardLimit
com.siemens.polarion.ui.matrix.softLimit
This property defines the number of cells which, if exceeded, triggers a warning before displaying the
matrix.
The font set available in LiveDoc Documents and rich text fields, and font-substitution for import and
round-trip operations, are configurable in the system propertycom.polarion.ui.richText.fonts.
Font substitution replaces certain fonts with fonts defined in Polarion. Any font not available in Polarion,
and for which there is no substitution set, is replaced by Polarion's default font.
Available fonts are separated by semicolon, and font substitution is separated by a comma. Consider the
following example.
• Arial, Courier New, Georgia, and Times New Roman are set as available fonts.
• Helvetica is substituted by Arial
• Courier, monospace, and HanWangKanTan are substituted by Courier New, etc.
The defined fonts must be installed on client computers. Any missing fonts will be substituted by the
default font, which is Segoe UI. This is hard-coded into Polarion and cannot be changed by administrators.
A poorly designed query sent to Lucene, or the PosgreSQL database index, can return an extremely large
number of objects, which are then resolved. This can require a great deal of Java heap memory, take
a long time to process, and the results of a single query may never be actually returned to the user's
browser interface. Also, the processing of so much data can launch the garbage collection process in a
loop. Garbage collection ties up the CPU, freezes the Java virtual machine for up to several minutes, and
can lead to an endless loop and an Out of Memory (OOM) error.
Administrators can set the following two system configuration properties to limit the size of query results.
One causes very large requests initiated by users from the web interface to be rejected and stopped from
running. Consequently, users are forced to optimize queries to reduce the number of returned objects
to less than the configured limits. Another detects large requested initiated by other means and writes
information to log files.
• com.siemens.polarion.platform.hardSearchSizeLimit
Defines a hard limit of maximum Lucene and database query result size to prevent Out of Memory
Errors. If this query limit is exceeded, the warning message below appears or an exception is thrown to
API/WS calls and the query is stopped.
Example
We are sorry, but your query below returns more than the maximum allowed limit of 100 000 objects.
Please refine it or refer to the Lucene and DB Query Limits section in Polarion Help.
[query that caused the warning]
• com.siemens.polarion.platform.softSearchSizeLimit
Defines a soft limit for the maximum Lucene and database query result size to prevent Out of Memory
Errors. If exceeded, a warning message is written to the log files, but the query is not stopped.
Warning
If you set too low a value in this property, and many users subsequently run queries that exceed the
limit, then the logs can become heavily polluted.
Note
After a period of evaluation of internal and customer-supplied usage data, it is possible that the
default value of the above properties might change in a future release, or the possibility to configure
these limits may be removed, and the limit values hard-coded. If so, it will be announced in
the 5_Required_Config_changes.txt file bundled with the relevant release distributions, and
documented in online Help.
For current default values and other information, see the System Configuration Properties Reference
document in the Polarion section of Support Center for more information.
• The above properties serve as a rearguard against overly large query results. The best defense is
prevention ― users trained to write optimized queries that do not stress the system unduly.
• Administrators may want to monitor the log for instances of the soft limit being invoked. If present too
often, it's indicative of the need to train users to construct better optimized queries.
• Administrators should avoid increasing the default values of the above properties. Such an increase is
not recommended, as it increases the danger of OOM errors. Again, user education, and the use of
optimized queries are the recommended best practices.
In Version 2014-SR1, Polarion updated the embedded Apache Lucene query engines. The way indexed text
is split into words changed from the previous Lucene version. Administrators can control how words are
split during queries by using the following Polarion properties.
search.wordBoundaries
Defines how word boundaries are defined for the index. Two values are supported:
splitByPattern The input is split to words using a regex pattern. This is the default.
standard The word boundaries are defined according to the Unicode standard.
Note
• Always use standard for Asian languages.
• Changing the value of this property requires a reindexing of Polarion data because this
configuration controls how the data are indexed.
search.wordBoundaries.splitByPattern
The default value ensures that the text is split by white-space, and the leading and trailing sequences of
non-alphanumeric characters are removed from the remaining character sequences. The rest are words for
the index. For example: Hello! WI-1234 _help_. is split to words Hello, WI-1234, and help.
When updating to a new Polarion version, your current settings in JVM properties for Maven calculations
may result in an Out of Memory (OOM) error PermgenSpace. In this case, you will need to adjust JVM
memory values in the system file calculation.properties.
Cache statistics can help you configure Polarion's caches correctly and in accordance with your server load.
The statistics are generated both on daily basis, and just before a shutdown of the Polarion server. They
can be found in the main Polarion log file.
A formatted example of some of the cache statistics in the main Polarion log file:
Tip
Search for com.polarion.platform.spi.cache.CacheStats
Note
The actual output includes a much larger list of caches and their statistics.
The statistics are laid out in a table and the first column is always the name of the cache.
Tip
To configure the baseline-cache, administrators should search for baseline-cache in the ehcache.xml
file.
HITS:
The number of cache hits (positive reads from the cache storage I/O). Each hit is for a single object in
the cache and this value is highly dependent on the number of users and operations on the server. When
the number of users or operations on the sever increase, the values should also naturally increase. If the
counter does not increase it can lead to performance issues, because the server needs to resolve objects
from the underlying authoritative storage. For example, for data object caches (any cache with the dao
prefix) it means that objects need to be read from subversion storage and this can prolong operations,
degrading performance.
MISSES:
The number of cache misses (negative reads from cache storage I/O). Each miss is for a single object
in the cache. For persistent caches, the misses cause disk I/O issues and can degrade performance.
Administrators should check that these numbers do not increase rapidly after caches are fully saturated. If
this number is increasing it means that caches are incorrectly sized. (The cache is not able to accumulate
all items and there is a constant miss ratio.)
HIT_RATIO:
The ratio of cache hits to total cache accesses (hits + misses), as a percentage. Administrators should check
that the percentage is high for each cache, otherwise the cache is not effective, can cause disk I/O issues
and can degrade performance.
GETS:
The number of cache gets (reads). Each get is for a single object in the cache. The value represents the
total number of accesses to the cache - either positive or negative reads.
PUTS:
The number of cache puts (writes). Each put is for a single object in the cache. The value represents
the total number of insertions to the cache. For persistent caches, the puts cause disk I/O issues and can
lead to performance issues when it is done too frequently. Administrators should check that puts are not
increasing significantly over time. When behaving correctly the cache is able to hold values for a longer
period of time to cover the appropriate load on the server.
REMOVAL:
The number of cache removals. Each removal is for a single object in the cache. The value represents the
removal of objects from cache initiated by Polarion. (The object is no longer valid because of changes in
authoritative storage.) For example, for data object cache it means that the object was changed in the
subversion repository and needs to be loaded again to cache in the next access.
EVICTION:
The number of cache evictions (essential removal). Each removal is for a single object in the cache. The
value represents the removal of objects from cache initiated by the cache configuration. The number
of evictions should be as low as possible or zero. If the value is high, it means that the cache is sized
incorrectly and needs to be adjusted. (The cache is unable to hold Polarion objects based on authoritative
storage.) For example, for data object cache it means that objects coming from the subversion repository
cannot fit into the size of the cache.
Note
Both the columns and cache names may change in the future.
Ehcache configuration
Polarion uses the Ehcache library to speed up access to the Polarion data structures. It uses a
comprehensive set of individual caches for specific data. This data can have different sizing requirements
depending on the repository size, structure, and content. The larger the repository, the larger the caches
might be needed (together with other resources like RAM and disk space). You can check how the caches
are being used in View cache statistics. If you find out that some of the caches are too small, you can
adjust their size.
Polarion defines a default cache configuration in the ehcache.xml file. You must create your own custom
Ehcache configuration file (where you can adjust some parameters like the cache sizes, etc.) that overrides
the default file.
Warning
The Ehcache library was updated in the Polarion 20 R2 release. The new version uses a different
configuration file structure than the previous version, so if you are using a custom configuration from an
older version of Polarion, you need to update it to the new format manually.
See the Update your custom Ehcache configuration to new format section below for details.
Procedure
1. Copy default ehcache.xml file placed in the META-INF folder within the platform.jar file at:
%PLUGINS_DIR%/com.polarion.platform_%RELEASE_NUMBER%/platform.jar
to the folder [POLARION HOME]/polarion/configuration (Linux) or [POLARION HOME]
\polarion\configuration (Windows).
This will become your custom Ehcache configuration file.
2. Open the custom file for editing and remove the whole <service> XML tag (including its inner tags)
from the beginning of the file. It's located within the root <config> XML tag.
(If you don't, the file will not be applied, and you'll see an error message in the Polarion log file.)
3. Implement your changes for individual caches.
All tags inside the <config> tag except <cache-template> and <cache> are ignored and can be
deleted from the custom configuration file.
At startup, Polarion identifies the custom Ehcache configuration file and validates it against
the ehcache-core-3.8.xsd file (https://www.ehcache.org/documentation/3.8/xsds.html). If the
verification fails, a validation error message appears in the Polarion log file, your custom configuration
is ignored, and the default configuration is used instead. If the verification passes, the file is merged
with the default file, and the custom changes are applied.
4. Check the cache statistics to verify the impact of your changes to the cache usage.
Note
You need to restart Polarion to apply the changes in the custom configuration file.
The Ehcache library has been updated from version 2.6.3 to version 3.8 in the Polarion 20 R2 release. The
new version uses a different configuration file structure than the previous version, so if you are using a
custom configuration from an older version of Polarion, you need to update it to the new format manually.
Procedure
1. Before any change, backup your current existing custom ehcache.xml file, then apply steps 1 and 2
from the above, Create a new custom Ehcache configuration file section.
2. Reapply your custom cache settings to the new custom configuration file (following the new format
rules), and save.
3. Check the cache statistics to verify the impact of your changes to the cache usage.
Note
You need to restart Polarion to apply the changes in the custom configuration file.
Ehcache configuration
Polarion 2404 comes pre-configured to cache up to 30 000 user objects (not the same as active users).
Older versions were pre-configured to support 20 000. If you plan to have more, than we recommend
increasing dao-user and securityService caches.
Procedure
The other caches can be optimized later based on the real usage of the system. Cache statistics can
help you configure Polarion's caches correctly and in accordance with your server load. The statistics are
generated both on a daily basis and just before a shutdown of the Polarion server. They can be found in
the main Polarion log file.
Polarion provides the option to customize the DAO cache configuration via the file $POLARION HOME$/
polarion/configuration/ehcache.xml. The default configuration should be optimal for 8 GB Xmx
settings on the server, and should also work well for larger installations. However, administrators have the
option to adjust the cache size to store more objects in the in-memory cache.
The size of some objects may vary considerably. For example, you may have small manual Test Runs
that are significantly smaller than the expected 2 MB object size. It might be useful to resize the
cache for such objects. To do that, copy the ehcache.xml file from [POLARION_HOME]/polarion/plugins/
com.polarion.platform_x.y.z/platform.jar/META-INF/ to [POLARION_HOME]/polarion/configuration/, and
adjust relevant settings in the copy.
Tip
On Windows, replace forward slash characters in the above paths with backslashes ( \ ).
The x.y.z in the first path above denotes your current Polarion version. For example, if your current
version is 3.19.1, then the string would be platform_3.19.1. You can find this number after the word
Build in the Tool view of Navigation (the view where you access Help).
Polarion supports the use of a secret for communication through the AJP protocol, and we recommend
that you use them.
Procedure
1. Stop Polarion.
2. Open the polarion.conf file in a text editor.
Default file locations:
• Windows: C:\Polarion\bundled\apache\conf\extra\
• Linux: /etc/httpd/conf.d/
3. Find the ProxyPass line. It should look like the following:
ProxyPass /polarion ajp://127.0.0.1:8889/polarion timeout=600
4. Add secret=your_secret to the end of the line:
Example:
ProxyPass /polarion ajp://127.0.0.1:8889/polarion timeout=600
secret=your_secret
5. Restart the Apache service. If there's no error message, the configuration should be working.
6. Set the same secret value in the polarion.properties file by adding the following property:
TomcatService.ajp.secret=your_secret
7. Start Polarion.
Note
For Apache versions older than 2.4.42, the secret may be configured by adding the mod_jk module.
Troubleshooting
If the SVN server does not respond after changing the Apache configuration file:
Procedure
1. Add the ProxyPass ! directive on a new row within the two <Location> </Location> tags in
the polarionSVN.conf file.
File location:
• Windows: C:\Polarion\bundled\apache\conf\extra\
• Linux: /etc/httpd/conf.d/
5. Authentication guide
Overview and limitations
Warning
• If you are updating from a previous version of Polarion, read the Update Overview section before
configuring the new authentication.xml file.
• The code examples in this PDF will not work if they extend across pages. See the Authentication
Guide topic in the Administrator and User Help document on Support Center for examples that
you can safely copy and paste.
Polarion supports Single Sign-On (SSO) by means of third-party services and platforms. When Polarion
is properly configured, users of these services, referred to as "Identity providers" (IdP), can log on to
Polarion using their credentials for an external provider that uses one of the supported authentication
methods. Popular providers include Azure, Google, GitHub, LinkedIn and Facebook. This can be beneficial
to companies employing contractors to whom they want to grant access to their Polarion system, but who
are not in the company's corporate employee SSO system.
Polarion supports several methods for authenticating users logging on to the system. The currently
supported methods are: password file, LDAP, OAuth 2, SAML, Teamcenter Security Services, and
Kerberos. You can optionally configure the system to use multiple authentication providers.
Note
Using the password file method doesn't implement all the needed security standards (for example
password complexity checking, brute force protection, multi-factor authentication, forgot password
mechanism, and so on...), so we strongly recommend using the alternative authentication methods
based on SSO: LDAP, OAuth 2, and SAML. These providers have higher security standards, but Polarion
administrators should always check the current password policy requirements with the identity provider.
This guide is organized into sections that cover authentication configuration of new installations, and
updated installations. These main sections provide separate subsections with procedures and examples
specific to each authentication method.
Note
• The information in this Authentication guide replaces the Single Sign-on (SSO) with Polarion
document for version 21 R1 and subsequent versions.
• Teamcenter Share authentication must be configured in the authentication.xml file via OAuth 2.
• Administrators on Linux can grant users a basic level of Polarion administrative rights without giving
them system-wide privileges.
If they set up rootless access on Linux, selected users can:
Configuration approaches
For password, LDAP, OAuth 2, SAML and Teamcenter Security Services you create and maintain the
user authentication configuration in the authentication.xml file, which resides on the server's file system.
While you can access the file directly, we recommend that you use the built-in XML editor in global
Administration (see the method-specific topics for access information).
Tip
If you edit the authentication.xml file within Polarion, your changes take effect immediately and don't
require a Polarion restart.
This syntax-aware editor can help prevent syntax errors that would result in a broken configuration. Also,
if you copy examples from Help into a third-party editor, the configuration might not work if the charset
characters for spaces and line breaks that the editor is using are not compatible.
The Kerberos authentication methods is configured via system configuration properties in the
polarion.properties file, and cannot be reconfigured using authentication.xml if you are updating to
version 2404 from an older version.
Limitations
Please keep in mind the following limitations as you begin to approach authentication configuration:
• Caution
Direct SVN access to the default /repo location will stop working. If you use external tools that
require access to this location or need direct access for administrative purposes, you must make some
changes. See Direct SVN Access for details.
• Electronic Signatures (eSignatures) with OAuth 2 still support LDAP fallback, but it is now configured in
the authentication.xml file.
(For more information, see Electronic signatures and LDAP tips and tricks.)
• Subversion (SVN) repository access is disabled by default. (For more information, see Direct SVN
access.)
• Kerberos authentication cannot have LDAP fallback. Kerberos can only be configured via system
configuration properties in polarion.properties (strictly without authentication.xml), while LDAP can
only be configured via authentication.xml.
• The ssoHomePageUrl is deprecated for some authentication configuration scenarios. For details, see
Technical reference information > Miscellaneous > Deprecated system configuration property.
• License assignment for new users self-registered (with password), auto-created users (by SAML, OAuth2
or LDAP), or new users created by synchronization with LDAP is still configured in polarion.properties.
(For more information, see License allocation.)
• Warning
If the authentication.xml contains a mix of one or more LDAP configurations and a Password
configuration, then their order in the XML file matters. Order of elements in the <mapping> section
of LDAP configurations also matters. An out-of-place element can cause authentication failure. Details
for correct configuration are provided in the method-specfic topics, and relevant technical reference
topics in this guide.
Before proceeding, please review Recover from a misconfigured XML.
• Although not a limitation per se, it is worth noting that automatic creation of new user accounts
(Auto-create) needs to be configured per provider, rather than globally as it was in versions prior to
21 R1. This provides flexibility to implement multiple authentication methods when Auto-create is not
desired for all the configured methods.
Get started
Overview
Polarion supports SSO by means of third-party services and platforms. When Polarion is properly
configured, users of these services, referred to as "Identity providers" (IdP), can log on to Polarion using
their credentials for an external provider that uses one of the supported authentication methods. Popular
providers include Azure, Google, GitHub, LinkedIn and Facebook. This can be beneficial to companies
employing contractors to whom they want to grant access to their Polarion system, but who are not in the
company's corporate employee SSO system.
User authentication changed with Polarion version 21 R1. The password file authentication is the default
for a new installation, to enable the main administrator to log on. After that, you need to decide which
authentication method(s) you want your new system to use, and configure authentication accordingly.
The topics in this section provide information and configuration examples for implementing the currently
supported authentication methods.
Tip
Topics in this section apply only to configuring authentication for a new Polarion installation. For
information about authentication configuration for existing installations, begin with "Configure an
updated installation" > Overview.
Get started
Your first step is to read over the topic for the type of authentication you plan to use with Polarion (see
the list below). If you want to implement more than one type, look over the type-specific topics, and also
Configure multiple providers.
• LDAP
• OAuth 2
Teamcenter Share authentication must be configured in the authentication.xml file via OAuth 2. The
same section can be used for Polarion login, Teamcenter Share, or both.
• SAML
• Password
• Kerberos
• Teamcenter Security Services
LDAP
Note
You can create this file yourself, but we recommend that you do it within Polarion as follows.
The built-in XML editor prevents flaws that would result in a broken configuration. It prevents syntax
errors, inaccurate file location, and incorrect file access permissions. Creating the file in the built-in editor
also populates the XML header with the correct link to the XSD (XML Schema Definition) located on your
Polarion server.
Tip
Looking to set up direct SVN access through your web browser or an SVN client like Tortoise?
Procedure
1. Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure LDAP for.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
5. Click within the editor, and update your settings based on the following XML configuration example:
Tip
You can combine this with other authentication methods or define multiple LDAP configurations
in parallel.
(But if you combine LDAP with Password authentication, the order matters.)
</mapping>
</ldap>
</authentication>
• Tip
◦ You can use XML reserved characters in your values, but you must escape them.
◦ You can also hide your secrets in the User Account Vault.
• An example that includes User Groups and Roles, Auto-create, escaped XML character values,
secure secrets, enabled User and Group synchronization and LDAP authentication for Web
Services:
</autocreate>
</ldap>
</authentication>
Caution
The tags in the <mapping> tag must be in the following order, or they won't work.
a. <id> (required)
b. <name> (none, one or multiple)
c. <email> (none, one or multiple)
d. <description> (none, one or multiple)
6. Click Save.
7. (Optional) You can now store the LDAP bind password in a secret securely.
b. Enter a key name (for example, myLdapBindPwd) in the Key field and the username in the User
Name field. (The username can be any string. It won't be used in the XML).
c. Enter the password twice, click on the right and Save on the top left.
d. Now refer to this secret value in your LDAP configuration instead of exposing it as plain text and
Save.
(Somewhere within the <ldap> tags like the following:)
<ldap>
<bindPassword userAccountVaultKey="myLdapBindPwd"/>
…
</ldap>
Tip
When you want to update the LDAP bind password, you can do one of the following:
Tip
Explore the entire list of LDAP specific tags you can use and read the LDAP tips and tricks section for
more information.
If the authentication.xml only contains an LDAP configuration, then Polarion's native logon page is
displayed even if the <password ...> section is not included in the XML.
If you've configured LDAP with SAML or Oauth 2 providers then it will look something like this.
The button labels are taken from the <oauth2 id="your_button_label"> tag but can also be safely
changed using the <view> tag.
Tip
You can also adjust the logon dialog box size if you need to, or add/customize the icons in the
buttons for SAML and OAuth 2 providers.
If the authentication.xml contains a mix of one or more LDAP and a Password configuration, then their
order in the XML file matters.
The authentication providers are scanned in the given order, and the provided user credentials are
validated against them in the following order:
• If the provider has no record for the user or the LDAP configuration is incorrect, or LDAP is inaccessible,
then the next provider in the sequence is considered.
• If the provider has a record for a user and the password matches, the authentication passes.
• If the provider has a record for a user, and the password does not match, the authentication fails.
(The authentication process terminates and all other remaining providers in the sequence are skipped
and the user is denied access to Polarion.)
• Provider order comes into play when multiple providers have records for users with an identical ID.
Note
Order also matters when Auto-create is configured.
OAuth 2
After completing a new installation of Polarion 2404 you must configure OAuth 2 via the
authentication.xml file.
Note
• You can create this file yourself, but we recommend that you do it within Polarion as follows. The
built-in XML editor prevents flaws that would result in a broken configuration. It prevents syntax
errors, inaccurate file location, and incorrect file access permissions. Creating the file in the built-in
editor also populates the XML header with the correct link to the XSD (XML Schema Definition)
located on your Polarion server.
Tip
• Teamcenter Share authentication must be configured in the authentication.xml file via OAuth 2.
The same section can be used for Polarion login, Teamcenter Share, or both.
• Looking to set up direct SVN access through your web browser or an SVN client like Tortoise?
Procedure
1. Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure OAuth 2
for.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
5. Click within the editor, and update your settings based on the following XML configuration example:
Tip
You can combine OAuth 2 with other authentication methods or set up multiple OAuth2
providers in parallel.
• Tip
◦ You can use XML reserved characters in your values, but you must escape them.
◦ You can also hide your secrets in the User Account Vault.
• A complex OAuth 2 example that implements a secure secret, user mapping a defined scope,
Auto-create, and replaces characters like | that are forbidden in Polarion user IDs:
6. Click Save.
Note
If you already have users in the passwd_credientials file, check the file after the configuration and
remove any that remain.
Tip
• Looking to limit users authenticating via IdP that can Auto-create Polarion accounts? Use the
<entitlements> and <userClaim> tags.
• Explore the entire list of OAuth 2 specific you can use in the authentication.xml file.
• You can also configure OAuth 2 for electronic signatures.
If you combine multiple OAuth2 providers and password authentication, then the logon screen will look
something like this.
The button labels are taken from the <oauth2 id="your_button_label"> tag but can also be safely
changed using the <view> tag.
Tip
You can also adjust the logon dialog box size if you need to, or add/customize the icons in the
buttons for OAuth 2 and SAML providers.
Explore the following example to understand how the bare minimum configuration should look like on the
Polaron side to connect to particular providers successfully.
<globalRoles>
<role>user</role>
</globalRoles>
</autocreate>
</oauth2>
<oauth2 id="Github_example">
<!-- ### The settings for the OAuth2 app on Github side can be
found at: https://github.com/organizations/[Your_organization_account_here]/
settings/applications/ -->
<!-- ### For the info about user's details structure see: https://
docs.github.com/en/rest/reference/users#get-the-authenticated-user -->
<authorizeUrl>https://github.com/login/oauth/authorize</
authorizeUrl>
<tokenUrl>https://github.com/login/oauth/access_token</tokenUrl>
<userUrl>https://api.github.com/user</userUrl>
<clientId>[Your_github_client_ID_here]</clientId>
<clientSecret>[Your_github_secret_here]</clientSecret>
<mapping>
<id>id</id>
<name>name</name>
<email>email</email>
</mapping>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
</globalRoles>
</autocreate>
</oauth2>
<oauth2 id="Google_example">
<!-- ### The settings for the OAuth2 app on Google
side can be found at: https://console.cloud.google.com/apis/credentials?
project=[Your_Google_project_id_here] -->
<!-- ### For the info about user's details structure see
"tokeninfo endpoint" at: https://developers.google.com/identity/sign-in/web/
backend-auth-->
<authorizeUrl>https://accounts.google.com/o/oauth2/v2/auth</
authorizeUrl>
<tokenUrl>https://oauth2.googleapis.com/token</tokenUrl>
<clientId>[Your_Google_clientID_here]</clientId>
<clientSecret>[Your_Google_secret_here]</clientSecret>
<mapping>
<id>sub</id>
<name>name</name>
<email>email</email>
</mapping>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
</globalRoles>
</autocreate>
</oauth2>
<oauth2 id="LinkedIn_example">
<!-- ### The settings for the OAuth2 app on LinkedIn side can be
found at: https://www.linkedin.com/developers/ > MyApps > select your app
-->
<!-- ### For the info about user's details structure see: https://
docs.microsoft.com/en-us/linkedin/shared/integrations/people/profile-api -->
<authorizeUrl>https://www.linkedin.com/oauth/v2/authorization</
authorizeUrl>
<tokenUrl>https://www.linkedin.com/oauth/v2/accessToken</tokenUrl>
<clientId>[Your_LinkedIn_client_id]</clientId>
<clientSecret>[Your_LinkedIn_secret]</clientSecret>
<userUrl>https://api.linkedin.com/v2/me</userUrl>
<scopes>
<scope>r_liteprofile</scope>
<scope>r_emailaddress</scope>
</scopes>
<mapping>
<id>id</id>
<name>localizedLastName</name>
</mapping>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
</globalRoles>
</autocreate>
</oauth2>
</authentication>
Caution
If you configured Teamcenter Share with Polarion 21 R2 (using Polarion properties) you must do the
following first:
1. Delete the old configuration from the Teamcenter Share Admin Console's Product
Configuration section.
2. Create a new configuration in Teamcenter Share Admin Console's Product Configuration and
select Polarion 2404 as the product name. (Generates new keys.)
You can configure OAuth 2 to be used for Teamcenter Share authentication by defining Teamcenter Share
in the <usedFor> tag.
• An OAuth 2 configuration without the <usedFor> tag is only used for Polarion login authentication.
• Add <xceleratorShare/> within the <usedFor>...</usedFor> tags to only use OAuth 2 for
Teamcenter Share authentication.
OAuth 2 example with both Teamcenter Share and Polarion login authentication configured:
<oauth2 id="xcelerator_simple_sample">
<authorizeUrl>https://samauth.us-east-1.sws.siemens.com/auth</
authorizeUrl>
<tokenUrl>https://samauth.us-east-1.sws.siemens.com/token</tokenUrl>
<clientId>[A client ID]</clientId>
<clientSecret>[A secret]</clientSecret>
<userUrl>https://samauth.us-east-1.sws.siemens.com/me</userUrl>
<accessKeyInfoUrl>https://samauth.us-east-1.sws.siemens.com/sam/
getAccessKey</accessKeyInfoUrl>
<introspectionUrl>https://samauth.us-east-1.sws.siemens.com/token/
introspection</introspectionUrl>
<nonce />
<responseParser>jsonpath</responseParser>
<mapping>
<id>$.userid</id>
<name>$.given_name</name>
<email>$.email</email>
</mapping>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>admin</role>
</globalRoles>
</autocreate>
<usedFor>
<xceleratorShare/>
<login/>
</usedFor>
</oauth2>
Note
The <login/>, <mapping> and <autocreate> tags are not required for Teamcenter Share only
authentication, but you must include them if you want to use a single/same authentication provider for
both Polarion and Teamcenter Share.
SAML
SAML
After completing a new installation of Polarion 2404 you must configure SAML via the authentication.xml
file.
Note
You can create this file yourself, but we recommend that you do it within Polarion as follows.
The built-in XML editor prevents flaws that would result in a broken configuration. It prevents syntax
errors, inaccurate file location, and incorrect file access permissions. Creating the file in the built-in editor
also populates the XML header with the correct link to the XSD (XML Schema Definition) located on your
Polarion server.
Tip
Looking to set up direct SVN access through your web browser or an SVN client like Tortoise?
Procedure
1. Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure SAML for.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
5. Click within the editor, paste one of the following example XML configurations there, and update it
with your settings:
Tip
You can combine SAML with other authentication methods or set up multiple SAML providers in
parallel.
</autocreate>
</saml>
</authentication>
• Note
You can use XML reserved characters in your values, but you must escape them.
Note
It is highly recommended to configure a proper metadata URL for your SAML provider in the
identityProviderMetadataUrl parameter to prevent unexpected issues arising from manual
misconfiguration.
• A SAML example that implements user mapping, Auto-create, user Group synchronization and
replaces characters like | that are forbidden in Polarion user IDs:
(Standard SAML configurations are not usually this complex.)
6. Click Save.
Note
If you already have users in the passwd_credientials file, check the file after the configuration and
remove any that remain.
Tip
Explore the entire list of SAML specific tags you can use in the authentication.xml file.
If you combine multiple SAML providers and password authentication, then the logon screen will look
something like this.
The button labels are taken from the <saml id="your_button_label"> tag but can also be safely
changed using the <view> tag.
Tip
You can also adjust the logon dialog box size if you need to, or add/customize the icons in the
buttons for SAML and OAuth 2 providers.
There are several different solutions available on the market that provide the SAML Identity. Since each
of the provided solutions is different and can be highly customized, the description on how to set up the
configuration on the SAML server side surely exceeds the scope and the ambitions of this Polarion’s help.
However, there is an easy way to know what data are sent from the SAML Identity Server and which values
can be utilized in the detailed configuration on Polarion’s side (for example for user-group synchronization,
field-mapping, and so on).
First steps
Procedure
1. Set up the simplest minimal working authentication configuration using the SAML protocol with
an administrative account. The configuration can be set up in the <saml … /> section in the
authentication.xml.
2. Install and open the SAML-tracer extension in your preferred browser to be able to sniff the
conversation between Polarion and the SAML Identity Server.
3. With the SAML-tracer extension tool open in your browser, log in to Polarion via the SAML protocol.
4. Find the SAML XML document sent by the SAML server to Polarion in the conversation between the
SAML Identity Server and the Polarion server.
Procedure
1. Find the attribute where the SAML Identity Server sends information about the user’s group. In this
example it is <Attribute Name=”member_of”.../>
2. Add or update the <groupsSynchronization … /> section in the SAML section of the
authentication.xml to point to the name of the attribute identified in the previous step:
<saml id="...">
…
<groupsSynchronization>
<enabled>true</enabled>
<groupsMapping>
<namePath>member_of</namePath>
</groupsMapping>
</groupsSynchronization>
</saml>
Next time when the user from the example above logs in to Polarion via SAML, they automatically
become a member of the following groups in Polarion: GroupA, GroupB.
Procedure
1. Find the name of the attribute where the SAML Identity Server sends the desired information about
the user, and update the user's profile on the Polarion side accordingly. For example, take the user’s
email sent by the SAML provider and map it in the Description field in the user’s profile on the
Polarion side.
Note
The FriendlyName value is not suitable for this purpose, please use the Name value instead.
2. Adjust the authentication.xml configuration: add or adjust the <mapping … /> section in the desired
SAML section by pointing the configuration to the name of the attribute from the previous step. In
this example it is as follows:
<saml id="...">
...
<mapping>
<description>urn:oid:1.2.840.113549.1.9.1</description>
</mapping>
...
</saml>
When the user from the example above logs in to Polarion via SAML the next time, their profile gets
automatically updated as follows:
In an Azure environment
<groupsMapping>
<namePath>http://schemas.microsoft.com/ws/2008/06/identity/claims/groups</
namePath>
</groupsMapping>
Azure only sends the groupId parameter by default. An administrator can change this setting by
following the description under the following link: https://learn.microsoft.com/en-us/answers/questions/
1092086/group-claim-for-sso-cloud-only-group-display-names
Password
After completing the new installation, Password authentication is the default authentication method
and works right out of the box. However, you can configure password authentication via the
authentication.xml file too so that you can easily add additional authentication methods at a later date.
Note
You can create this file yourself, but we recommend that you do it within Polarion as follows.
The built-in XML editor prevents flaws that would result in a broken configuration. It prevents syntax
errors, inaccurate file location, and incorrect file access permissions. Creating the file in the built-in editor
also populates the XML header with the correct link to the XSD (XML Schema Definition) located on your
Polarion server.
The Password authentication ID is polarion_login_form and cannot be changed, but the name
displayed in the configured authentication providers is localizable and set to Polarion login form
by default.
Tip
Looking to set up direct SVN access through your web browser or an SVN client like Tortoise?
Procedure
1. Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure Password
authentication for.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
5. Click within the editor, paste one of the following example XML configurations there, and update it
with your settings:
Caution
You can combine Password authentication with other authentication methods but if you combine
it with LDAP, the order matters.
• Tip
You can use XML reserved characters in your values, but you must escape them.
6. Click Save.
What to do next
Tip
Explore the entire list of password specific tags you can use in the authentication.xml file.
If you combine password authentication with other SAML or OAuth 2 providers, then the logon screen
will look something like this.
The button labels are taken from the <oauth2 id="your_button_label"> tag but can also be safely
changed using the <view> tag.
Tip
You can also adjust the logon dialog box size if you need to.
Kerberos SSO
Tip
If you use Kerberos with an authentication fallback, configure it on the side of an external authentication
provider, not the Polarion side.
Caution
The Kerberos authentication method will be deprecated in future versions of Polarion.
1. The client machine logs into the domain and obtains a Kerberos token.
2. If the browser is configured to use the Kerberos token for authentication, the browser sends this
token when negotiating authentication with a site that is a member of the same domain.
3. The Polarion server gets the token from the client and validates it against the domain controller.
4. If the domain controller successfully validates the token, Polarion authenticates the user and logs
them in.
A set of prerequisites is required in order to configure Polarion to authenticate using Kerberos tokens:
Procedure
1. All involved machines need to be members of the same domain for example, <yourdomain.com>
a. Domain server (<kdc.yourdomain.com>) that hosts KDC (Key Distribution Center) and DNS
services.
b. Domain users (for example, user1) that log into client machines.
c. Polarion service provider (for example, <polarion-server.yourdomain.com>) that represents the
server running Polarion.
2. Client and Polarion machines need to have corresponding domain accounts (principals):
Domain user: <[email protected]>
Polarion service: <HTTP/[email protected]>
3. Client browsers are configured for Kerberos authentication.
4. A keytab file with the password key for the Polarion service principal needs to be generated on the
domain server.
a. On Windows run the following command as an administrator on your domain server.
ktpass -out polarion.keytab -princ HTTP/polarion-
[email protected] -mapuser polarion-server -kvno 0
-crypto AES128-SHA1 -pass password.123 -ptype KRB5_NT_PRINCIPAL
Note
You should align the keytab encryption with the domain's user settings.
(HTTP must be in the principal name.)
b. On Linux run the following command as a root user on your Domain server replacing
<yourdomain> with your own.
ktadd -norandkey -k /tmp/polarion-server.keytab HTTP/polarion-
[email protected]
See the example to follow and refer to the correct values for each ktpass command attribute.
• The HTTP service component in the principal name is required, otherwise a Kerberos authentication
with the polarion-server will not work.
• The Polarion service provider principal must contain the fully qualified domain name of the machine's
(FQDN).
• Polarion's Kerberos SSO authentication requires that principals use AES 128 bit encryption.
1. In the Windows domain, all user accounts must have the following configuration checked:
Properties→ Account→ Account options→ This account supports Kerberos AES 128 bit
encryption.
2. In the Linux realm, the encryption needs to be set properly when adding the following principal:
For example:
addprinc -e aes128-cts -randkey HTTP/[email protected]
3. The DES encryption type is not considered secure, so it is not allowed in the default configuration
of many operating systems.
• The generated keytab needs to respect this configuration as well, so make sure to set the -crypto option
below so that it’s in line with the principal configuration.
• Kerberos always passes the sAMAccountName attribute as the user's principal name, so this field also
represents the userId in Polarion. If you need to synchronize additional user attributes from LDAP, please
refer to the Administrator's Guide → Managing Users & Permissions → Configuring Polarion for
LDAP User Synchronization section in Polarion's Help.
Polarion configuration
Procedure
1. Copy the generated polarion.keytab file to the Polarion server under Polarion's configuration
directory.
2. On the Polarion server, create a login.conf file in Polarion's configuration directory with the
following data:
For Linux:
Polarion {
com.sun.security.auth.module.Krb5LoginModule required
doNotPrompt=true principal="HTTP/polarion-
[email protected]"
useKeyTab=true keyTab="/opt/polarion/polarion/configuration/polarion-
server.keytab";
};
For Windows:
Polarion {
com.sun.security.auth.module.Krb5LoginModule required
doNotPrompt=true principal="HTTP/polarion-
[email protected]"
useKeyTab=true keyTab="C:/Polarion/polarion/configuration/polarion-
server.keytab";
};
3. Configure Polarion to use SPNEGO authentication and set the following properties in the
polarion.properties file:
File location:
Linux: /opt/polarion/etc/polarion.properties
Windows: C:/Polarion/polarion/configuration/polarion.properties
Once you have successfully configured the domain, the domain server, the domain client and the Polarion
server, users will not see the Polarion login page, but will be immediately authenticated using the provided
Kerberos token and logged into Polarion as the same user with same login ID.
All currently supported browsers can be configured to use Kerberos authentication with Polarion.
All currently supported browsers (found in the Release Notes section of the README.html file), can be
configured to use Kerberos authentication with Polarion.
Procedure
Chrome on Linux
Procedure
Procedure
Note
As of Polarion 21 R1 you can no longer use LDAP as a fallback authentication method.
If you use Kerberos with an authentication fallback, configure it on the side of an external authentication
provider, not the Polarion side.
Caution
The Kerberos authentication method will be deprecated in future versions of Polarion.
A typical setup for enterprise customers has two user types with different authentication methods:
• Internal Users: Operate from within the network and are authenticated in the domain.
• External Users: Customers or contractors who are not authenticated in the domain, but access the
internal network via a VPN connection.
Polarion supports both user types while still leveraging the benefits of SSO.
When the authentication fallback is configured, users are presented with the standard Polarion login
screen when they do not provide a Kerberos authentication token.
Procedure
Tip
When using Edge or Chrome, users may be prompted for credentials if the Use Integrated Windows
Authentication option is enabled in Internet Options and Polarion is configured for Kerberos SSO. If
a user cannot be authenticated in the domain to get the correct Kerberos ticket, then they can simply
discard the prompt for credentials three times and will then be redirected to the Polarion login screen.
After completing a new installation of Polarion 2404 you must configure Teamcenter Security Services via
the authentication.xml file that resides on the server's file system.
Note
You can create this file yourself, but we recommend that you do it within Polarion as follows.
The built-in XML editor prevents flaws that would result in a broken configuration. It prevents syntax
errors, inaccurate file location, and incorrect file access permissions. Creating the file in the built-in editor
also populates the XML header with the correct link to the XSD (XML Schema Definition) located on your
Polarion server.
Procedure
1. Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure
Teamcenter Security Services for.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
5. Click within the editor, and update your settings based on the following XML configuration example:
Warning
You cannot combine Teamcenter Security Services with other authentication methods or set up
multiple providers in parallel, except for LDAP fallback for electronic signatures.
• A complex Teamcenter Security Services example that implements Auto-create, custom request
attributes and LDAP fallback for E-Signatures:
(Also requires an LDAP configuration.)
<ldap id="ldap_simple_sample">
<url>ldap://ldapprovider.example.com:389</url>
<baseDn>OU=users,DC=example</baseDn>
<bindDn>CN=binduser,OU=users,DC=example</bindDn>
<bindPassword>[Your_password_as_plain_text_here]</
bindPassword>
<mapping>
<id>uid</id>
</mapping>
6. Click Save.
7. Add the following AppID configuration property to the polarion.properties file.
com.siemens.polarion.security.appId=Polarion
(The default value is Polarion.)
8. Restart Polarion.
Once you have successfully configured Teamcenter Security Services and the Polarion server, users do not
see Polarion's logon page but are immediately redirected to the Teamcenter Security Services logon page
to enter their credentials. After authenticating in Teamcenter Security Services, an SSO session is created,
users are redirected back to Polarion and logged on as the same user with the same logon ID.
Overview
User authentication changed with Polarion version 21 R1. Depending on the user authentication method
configured for an existing installation older than that version, you may need to reconfigure authentication
when updating an older version to version 21 R1 (or a subsequent release). The topics in this section
provide information and configuration examples for the currently supported authentication methods (see
the list below).
Tip
Topics in this section apply only to updating an existing Polarion installation.
For new installations, begin with the Overview topic in the Configure a new installation section.
• If you use LDAP to log on, or as a fallback mechanism for electronic signatures, you must configure
LDAP in the new authentication.xml file. Use the built-in syntax-aware XML editor in the User
Management Authentication page of global Administration to edit this file.
Caution
Be careful when configuring the new authentication file. If you don't have access to the file system,
a misconfiguration might lock you out of Polarion, and you will need to contact your Polarion
administrator.
• No changes were made to the Kerberos configuration. If you've already configured it in Polarion, no
further changes are required unless you configured LDAP as a fallback authentication method.
Note
As of Polarion 21 R1 you can no longer use LDAP as a fallback authentication method.
(LDAP is now configured in the new authentication.xml file.)
If you use Kerberos with an authentication fallback, configure it on the side of an external
authentication provider, not the Polarion side.
• Warning
Instead of the passwd file, a new passwd_credentials file now stores local passwords for local users.
The passwd file still exists, but is now exclusively used to store system-generated secrets for internal
Polarion processes.
◦ Administrators that made custom modifications to the passwd file prior to 21 R1 should apply them
to the passwd_credentials file instead.
◦ If you use external services that refer to the passwd file, adjust their configurations to point to the
passwd_credentials file instead.
• If you use a Cluster setup with load balancing, you must adjust your Apache configuration on the
Cluster machine where the load balancer is located.
These changes should be made after updating all machines that run the Polarion service.
1. Locate the loadbalancer.conf file in Apache configuration on the Cluster machine.
2. Replace the passwd file reference with a reference to the passwd_credentials file.
Do not change any other content. The new entry should look like the following:
<Location /balancer-manager>
SetHandler balancer-manager
Require all denied
AuthType Basic
AuthName "BalancerManager"
AuthUserFile "/opt/polarion/data/svn/passwd_credentials"
require valid-user
</Location>
Get started
Your first step is to read over the topic for the type of authentication your system already uses (see the list
below). If you plan to change to a different type, then read the topic for it. If you want to implement more
than one type, look over the pertinent type-specific topics, and also Configure multiple providers.
Tip
Want to make the migration of existing configured authenticators easier?
Use the migration tool that comes with the Polarion distribution.
Note: The XML the tool generates is a rough draft and must be reviewed and adjusted by an
administrator before deploying it.
• LDAP
• OAuth 2
Teamcenter Share authentication must be configured in the authentication.xml file via OAuth 2. The
same section can be used for Polarion login, Teamcenter Share, or both.
• SAML
• Password
• Kerberos
• Teamcenter Security Services
LDAP
Before Polarion 21R1, LDAP was configured in the Apache configuration, the polarion.properties file and
Polarion's administration.
You must now do it all in the authentication.xml file. Follow the instructions below to migrate your
configuration before removing your old configuration.
Warning
• If you are updating from a previous version of Polarion, read the Update Overview section before
configuring the new authentication.xml file.
• The code examples in this PDF will not work if they extend across pages. See the Authentication
Guide topic in the Administrator and User Help document on Support Center for examples that
you can safely copy and paste.
Tip
Want to make the migration of existing configured authenticators easier?
Use the migration tool that comes with the Polarion distribution.
Note: The XML the tool generates is a rough draft and must be reviewed and adjusted by an
administrator before deploying it.
Warning
Significant changes were made in Polarion 21 R1 to the way LDAP is configured and stored. Before you
update, you should:
• Make screenshots of all your previous LDAP settings before you start updating.
(Some LDAP administration pages are deprecated and will disappear once you update.)
• Make sure that you don't lose administration access during the update.
If your administration account uses LDAP for authentication, make sure that you know all the settings
required to reconnect to the LDAP server. (Because the Apache configuration for LDAP won't work with
Polarion after the update.)
• Temporarily allow for authentication against the local password file and set up a local service account
with all administrative permissions. (This local super-admin account serves as a recovery backup and
can be deleted once the updated LDAP configuration is up and running.) Once the account is set up,
you should also backup a copy of the passwd file in the /svn folder.
• Explore or print the comparison table to get an idea of the scope and specifics that were changed.
Procedure
1. Follow the instructions in the 2_How_to_update_Polarion.txt file within the update package to
update Polarion.
(Once you do, you will not be able to authenticate to Polarion using LDAP until you complete the new
configuration.)
2. Remove the previous LDAP references from your Apache configuration dedicated to Polarion and
restart the Apache service.
Warning
• Pay special attention to the AuthBasicProvider setting in the polarionSVN.conf file.
(This line cannot refer to ldap and must be: AuthBasicProvider file.)
• To allow direct external access to the SVN repository (not recommended), see Direct SVN access
for details.
3. Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure LDAP for.
4. Now it's time to create a new authentication.xml file and migrate the LDAP configuration there.
Tip
• You can create this file yourself, but we recommend that you do it within Polarion as follows.
The built-in XML editor prevents flaws that would result in a broken configuration. It prevents
syntax errors, inaccurate file location, and incorrect file access permissions. Creating the file in
the built-in editor also populates the XML header with the correct link to the XSD (XML Schema
Definition) located on your Polarion server.
• If you do decide to create it manually, you must restart the Polarion service for your changes to
take effect.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
8. Click within the editor, and update your settings based on the following XML configuration example:
If you use a local service account authenticated against the local password file, you must add
<password default="true"/> to the XML like the example below.
(If you do, placing it before or after the <ldap> tags changes the configuration.)
Caution
The tags in the <mapping> tag must be in the following order, or they won't work.
a. <id> (required)
b. <name> (none, one or multiple)
c. <email> (none, one or multiple)
d. <description> (none, one or multiple)
Based on whether your LDAP directory uses a flat-list or hierarchical-structure you might consider
adding the <searchSubtree>true</searchSubtree> directive shown in the example above. By
default, when this tag is omitted, the directories nested below the level specified by the <baseDn/>
tag are not searched.
9. Click Save.
The settings are immediately applied and your users should be able to log on again via your LDAP
service.
Warning
A misconfiguration of the authentication.xml file could result in you being unable to log onto
Polarion.
See Recover from a misconfiguration to learn how to avoid it and fix a misconfiguration if it
occurs.
10. Once you've confirmed that your new authentication configuration is working, you can go ahead and
delete the temporary service account you created.
11. (Optional) You can store the LDAP bind password in a secret securely.
12. When everything works as it should, it's time to remove the now-orphaned LDAP-related records from
your polarion.properties file, since they are now inactive. In this case, it is not necessary to restart
the Polarion server.
Warning
As of Polarion 21 R1, direct external access to the SVN repository must be explicitly configured.
<baseDn>cn=users,dc=company,dc=com<
#AuthLDAPURL "ldap://host:port/ /baseDn>
basedn?attribute?scope?filter" <mapping>
AuthLDAPURL <id>sAMAccountName</id>
"ldap://host.example.com:389/ </mapping>
cn=users,dc=company,dc=com? <searchSubtree>true</
searchSubtree>
sAMAccountName?sub? <searchFilter>objectclass=user</
(objectclass=user)" searchFilter>
</ldap>
The user and password for the LDAP server to <ldap id="ldap_id">
perform searches.
<bindDn>cn=exampleUser,cn=users,
(Typically in the PolarionSVN.conf file): dc=company,dc=com</bindDn>
<bindPaassword>examplePassword</
AuthLDAPBindDN bindPaassword> ...
"cn=exampleUser,cn=users,dc=company </ldap>
,dc=com"
AuthLDAPBindPassword
"examplePassword"
The order that you want to combine Polarion-only The order of the <password/> and <ldap/> tags
users with organization-wide users. in the authentication.xml file matters.
(Typically in the PolarionSVN.conf file): It defines the order that the authentication is
processed in .
Example 1:
Example 1:
AuthBasicProvider file ldapFoo
ldapBoo <authentication …>
<password … />
Example 2: <ldap id=”ldapFoo” … />
</authentication>
Example 2:
<authentication …>
<ldap … />
<password … />
...
</authentication>
Follow referrals in the Apache configuration A boolean parameter with true/false values.
When true, Java gets the value follow; when
(Typically in the PolarionSVN.conf file) false, it gets ignore. The default value is null -
unspecified, and Java will use its default. (May
#LDAPReferrals On/Off depend on the protocol version).
Limit the depth of nested referrals in the Apache The integer parameter. It limits the depth of nested
configuration referrals.
Dereference aliases in the Apache configuration The parameter to dereference aliases. The
allowed values are: always, never, finding,
(Typically in the PolarionSVN.conf file) searching. The default value is null -
unspecified. (Default Java behavior)
#AuthLDAPDereferenceAliases
<ldap ...>
AuthLDAPDereferenceAliases never <derefAliases>never</
derefAliases> ...
</ldap>
<ldap id=”ldap_id”>
...
<synchronization>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
<role>custom_role</
role>
</globalRoles>
</synchronization>
</ldap>
Advanced mapping of fields in user profiles for user You can now configure this advanced mapping for
synchronization: each LDAP provider independently.
<ldap id=”ldap_id”>
...
<mapping>
<id> sAMAccountName</id>
<name>%cn%</name>
<email>%email%</email>
<description>%description%</
description>
</mapping>
Additional user sync settings like search in User synchronization settings, like search, can
now be configured for each LDAP provider
Polarion's Administration.
independently:
<ldap id=”ldap_id”>
…
<searchSubtree>true</
searchSubtree>
<searchSizeLimit>2000</
searchSizeLimit>
<searchPageSize>1000</
searchPageSize>
</ldap>
Allow LDAP to be used for Web Service You can now configure each LDAP provider for
authentication over Web Services independently.
authentication in Polarion's Administration.
<ldap id=”ldap_id”
allowWebServices="true" ...>
…
</ldap>
User Group Synchronization. A single LDAP provider can now be set for User
Group synchronization.
<ldap id=”ldap_id”
syncUserGroups="true" ...>
…
</ldap>
Because the configuration was not XML, no The characters reserved for XML syntax must now
characters were reserved for XML syntax. be escaped individually:
<![CDATA[(&(field1=foo)
(field2=boo))]]>
OAuth 2
Warning
• If you are updating from a previous version of Polarion, read the Update Overview section before
configuring the new authentication.xml file.
• The code examples in this PDF will not work if they extend across pages. See the Authentication
Guide topic in the Administrator and User Help document on Support Center for examples that
you can safely copy and paste.
Tip
Want to make the migration of existing configured authenticators easier?
Use the migration tool that comes with the Polarion distribution.
Note: The XML the tool generates is a rough draft and must be reviewed and adjusted by an
administrator before deploying it.
If your Polarion is configured for SSO via OAuth 2, the update is pretty straightforward.
Warning
• Since Polarion 21R1, the OAuth2 configuration in the polarion.properties is no longer actively
developed. To guarantee the functionality, every OAuth2 configuration has to be migrated to the
authentication.xml file.
• If you use LDAP authentication for electronic signatures, you must configure OAuth 2 via the
authentication.xml file as described below.
• Teamcenter Share authentication must be configured in the authentication.xml file via OAuth 2.
The same section can be used for Polarion login, Teamcenter Share, or both.
Procedure
1. Follow the instructions in the 2_How_to_update_Polarion.txt file within the update package to
update Polarion.
2. (Optional) Convert your polarion.properties based configuration to the new authentication.xml file.
Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure the OAuth
2 authentication.xml based configuration for.
Tip
• You can create this file yourself, but we recommend that you do it within Polarion as follows.
The built-in XML editor prevents flaws that would result in a broken configuration. It prevents
syntax errors, inaccurate file location, and incorrect file access permissions. Creating the file in
the built-in editor also populates the XML header with the correct link to the XSD (XML Schema
Definition) located on your Polarion server.
• If you do decide to create it manually, you must restart the Polarion service for your changes to
take effect.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
6. Click within the editor, and begin adding your configuration XML based on the table below:
Tip
• Looking for a complex OAuth 2 example that you can paste into the authetication.xml file then
customize?
(It implements a secure secret, user mapping a defined scope and Auto-create.)
• You can also customize the icon in the button for OAuth 2 and SAML providers.
• Looking to limit users authenticating via IdP that can Auto-create Polarion accounts? Use the
<entitlements> and <userClaim> tags.
• You should also explore the entire list of Oauth 2 specific tags you can use.
7. Click Save.
8. When everything works as it should, it's time to remove the now-orphaned OAuth 2-related records
from your polarion.properties file, since they are now inactive. In this case, it is not necessary to
restart the Polarion server.
Note
During the migration process, some users may remain in the passwd_credientials file.
Check the file after the migration and remove any that remain.
Tip
You can also configure OAuth 2 for electronic signatures.
Caution
If you configured Teamcenter Share with Polarion 21 R2 (using Polarion properties) you must do the
following first:
1. Delete the old configuration from the Teamcenter Share Admin Console's Product
Configuration section.
You can configure OAuth 2 to be used for Teamcenter Share authentication by defining Teamcenter Share
in the <usedFor> tag.
• An OAuth 2 configuration without the <usedFor> tag is only used for Polarion login authentication.
• Add <xceleratorShare/> within the <usedFor>...</usedFor> tags to only use OAuth 2 for
Teamcenter Share authentication.
• Add both the <xceleratorShare/> and <login/> tags to use OAuth 2 for both Teamcenter Share
and Polarion login authentication.
Tip
See the Teamcenter Share-specific parameters section for additional Teamcenter Share parameters.
OAuth 2 example with both Teamcenter Share and Polarion login authentication configured:
<oauth2 id="xcelerator_simple_sample">
<authorizeUrl>https://samauth.us-east-1.sws.siemens.com/auth</
authorizeUrl>
<tokenUrl>https://samauth.us-east-1.sws.siemens.com/token</tokenUrl>
<clientId>[A client ID]</clientId>
<clientSecret>[A secret]</clientSecret>
<userUrl>https://samauth.us-east-1.sws.siemens.com/me</userUrl>
<accessKeyInfoUrl>https://samauth.us-east-1.sws.siemens.com/sam/
getAccessKey</accessKeyInfoUrl>
<introspectionUrl>https://samauth.us-east-1.sws.siemens.com/token/
introspection</introspectionUrl>
<nonce />
<responseParser>jsonpath</responseParser>
<mapping>
<id>$.userid</id>
<name>$.given_name</name>
<email>$.email</email>
</mapping>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>admin</role>
</globalRoles>
</autocreate>
<usedFor>
<xceleratorShare/>
<login/>
</usedFor>
</oauth2>
Note
The <login/>, <mapping> and <autocreate> tags are not required for Teamcenter Share only
authentication, but you must include them if you want to use a single/same authentication provider for
both Polarion and Teamcenter Share.
SAML
Warning
• If you are updating from a previous version of Polarion, read the Update Overview section before
configuring the new authentication.xml file.
• The code examples in this PDF will not work if they extend across pages. See the Authentication
Guide topic in the Administrator and User Help document on Support Center for examples that
you can safely copy and paste.
If your Polarion is configured for SSO via SAML, the update is pretty straightforward. While migrating
your SAML configuration to the authentication.xml file after updating to Polarion 21 R1 is optional,
we recommend that you do because it will let you combine SAML SSO with additional authentication
methods.
Warning
• Since Polarion 21R1, the SAML configuration in the polarion.properties is no longer actively
developed. To guarantee the functionality, every SAML configuration has to be migrated to the
authentication.xml file.
• If you use LDAP authentication for electronic signatures, you must configure SAML via the
authentication.xml file as described below.
Tip
Want to make the migration of existing configured authenticators easier?
Use the migration tool that comes with the Polarion distribution.
Note: The XML the tool generates is a rough draft and must be reviewed and adjusted by an
administrator before deploying it.
Procedure
1. Follow the instructions in the 2_How_to_update_Polarion.txt file within the update package to
update Polarion.
2. (Optional) Convert your polarion.properties based configuration to the new authentication.xml file.
Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure the SAML
authentication.xml based configuration for.
Tip
• You can create this file yourself, but we recommend that you do it within Polarion as follows.
The built-in XML editor prevents flaws that would result in a broken configuration. It prevents
syntax errors, inaccurate file location, and incorrect file access permissions. Creating the file in
the built-in editor also populates the XML header with the correct link to the XSD (XML Schema
Definition) located on your Polarion server.
• If you do decide to create it manually, you must restart the Polarion service for your changes to
take effect.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
6. Click within the editor, and begin adding your configuration XML based on the table below:
https://saml.example.com/adfs/ls/? Tip
wa=wsignout1.0
You can use XML reserved characters in your
values, but you must escape them.
Tip
• Looking for a complex SAML example that you can paste into the authetication.xml file then
customize?
• You can also customize the icon in the button for SAML and OAuth 2 providers.
• A SAML provider can also send a list of the Groups that a user is a member of. (See Synchronize
user Groups with SAML for details.)
• You should also explore the entire list of SAML specific tags you can use.
7. Click Save.
8. When everything works as it should, it's time to remove the now-orphaned SAML-related records from
your polarion.properties file, since they are now inactive. In this case, it is not necessary to restart
the Polarion server.
Note
During the migration process, some users may remain in the passwd_credientials file.
Check the file after the migration and remove any that remain.
Password
Warning
• If you are updating from a previous version of Polarion, read the Update Overview section before
configuring the new authentication.xml file.
• The code examples in this PDF will not work if they extend across pages. See the Authentication
Guide topic in the Administrator and User Help document on Support Center for examples that
you can safely copy and paste.
Tip
Want to make the migration of existing configured authenticators easier?
Use the migration tool that comes with the Polarion distribution.
Note: The XML the tool generates is a rough draft and must be reviewed and adjusted by an
administrator before deploying it.
If your Polarion is configured for authentication via passwords, the update is pretty straightforward.
Follow the instructions in the 2_How_to_update_Polarion.txt file within the update package to
update Polarion.
(If you don't want to migrate your settings to the new authentication.xml file, no further action is
required.)
Procedure
1. If you decide to convert your polarion.properties based configuration to the new authentication.xml
file.
Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure the OAuth
2 authentication.xml based configuration for.
Tip
• You can create this file yourself, but we recommend that you do it within Polarion as follows.
The built-in XML editor prevents flaws that would result in a broken configuration. It prevents
syntax errors, inaccurate file location, and incorrect file access permissions. Creating the file in
the built-in editor also populates the XML header with the correct link to the XSD (XML Schema
Definition) located on your Polarion server.
• If you do decide to create it manually, you must restart the Polarion service for your changes to
take effect.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
Caution
You can combine Password authentication with other authentication methods but if you combine
it with LDAP, the order matters.
6. Click Save.
7. When everything works as it should, it's time to remove the now-orphaned records related to
password authentication from your polarion.properties file, since they are now inactive. In this case,
it is not necessary to restart the Polarion server.
Tip
Explore the entire list of password specific tags you can use.
If you combine password authentication with SAML or OAuth 2 providers, then the logon screen will
look something like this.
The button labels are taken from the <oauth2 id="your_button_label"> tag but can also be safely
changed using the <view> tag.
Tip
You can also adjust the logon dialog box size if you need to.
Self registration
Note
If you allow new users to create their own Polarion account and adopt the new authentication.xml
method, you must transfer the following settings from the polarion.properties file to the
authentication.xml.
<role>custom_global_role</role>
</globalRoles>
</registration>
</password>
Tip
You can use XML reserved characters in your
values, but you must escape them.
All the additional settings stay in the polarion.properties file, if you use them. (For example,
minimalPasswordLength=)
Kerberos
No changes were made to the Kerberos authentication setup, but as of Polarion 21 R1 you can no longer
use LDAP as a fallback authentication method.
Tip
If you use Kerberos with an authentication fallback, configure it on the side of an external authentication
provider, not the Polarion side.
Caution
The Kerberos authentication method will be deprecated in future versions of Polarion.
Warning
• Since Polarion 21R1, the Teamcenter Security Services configuration in the polarion.properties is
no longer actively developed. To guarantee the functionality, every Teamcenter Security Services
configuration has to be migrated to the authentication.xml file.
• If you use LDAP authentication for electronic signatures, you must configure Teamcenter Security
Services via the authentication.xml file as described below.
Tip
If you use LDAP authentication for electronic signatures, use the migration tool (that ships with the
Polarion distribution) to get a minimal working authentication.xml configuration with support for
Teamcenter Security Services and LDAP E-Signatures.
Procedure
1. Follow the instructions in the 2_How_to_update_Polarion.txt file within the update package to
update Polarion.
2. (Optional) Convert your polarion.properties based configuration to the new authentication.xml file.
Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure the
Teamcenter Security Services authentication.xml based configuration for.
Tip
• You can create this file yourself, but we recommend that you do it within Polarion as follows.
• The built-in XML editor prevents flaws that would result in a broken configuration. It prevents
syntax errors, inaccurate file location, and incorrect file access permissions. Creating the file in
the built-in editor also populates the XML header with the correct link to the XSD (XML Schema
Definition) located on your Polarion server.
• If you do decide to create it manually, you must restart the Polarion service for your changes to
take effect.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
6. Click within the editor, and begin adding your configuration XML based on the table below:
com.siemens.polarion.security.tcsso Tip
.serviceUrl=http://tcss-server/
identity You can use XML reserved characters in your
values, but you must escape them.
Tip
Looking for a complex Teamcenter Security Services example that you can paste into the
authetication.xml file then customize?
(It implements Auto-create, custom request attributes and LDAP fallback for E-Signatures.)
You should also explore the entire list of Teamcenter Security Services-specific tags you can use.
7. Click Save.
8. When everything works as it should, it's time to remove the now-orphaned Teamcenter Security
Services-related records from your polarion.properties file, since they are now inactive. In this case,
it is not necessary to restart the Polarion server.
Procedure
1. Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure LDAP for.
Note
The XML header contains an automatically prefilled link to XSD (XML Schema Definition) located on
your Polarion server.
• Click Default Template to obtain the same initial XML sample visible when you follow the steps above.
We recommend that you only update the authentication.xml file via the built-in editor.
(Do not edit the authentication.xml file directly with an external editor.)
Warning
If you still decide to modify the authentication.xml file directly on the server, you will have to reindex
the coordinator.
In a typical multi-login configuration, when unauthenticated users access Polarion, they can select from
various configured logon options on the logon screen. If they click on some of the Log in with... options,
they are redirected to the selected provider's logon dialog box.
However, suppose that your configuration only supports a single authentication option. In that case, the
logon screen (with the only available option) is skipped, and users are redirected to the logon dialog of
your configured authentication provider.
To achieve this, the configuration in the authentication.xml file must be configured in one of the
following ways:
Tip
You can also customize the icon in the button for SAML and OAuth 2 providers.
Example:
<authentication..>
<ldap id="ldap_id1">
...
</ldap>
<ldap id="ldap_id2">
...
</ldap>
<oauth2 id="oauth_id" default="true" forceLdapEsignatures="true">
...
</oauth2>
</authentication>
• Multiple <saml> and <oauth2> sections can be combined in the authentication.xml file to allow
external collaborators into Polarion.
There is no limit to the number of combinations of SAML and OAuth 2 providers that you can configure.
• If want to use Teamcenter Share with Polarion, its authentication must be configured via OAuth 2.
(You can also configure Polarion login authentication along side it.)
• You can also keep some users with a local password (using <password>) when using network-
authenticated-SSO.
(You can only have a single <password> section the authentication.xml)
Tip
We recommend you keep a local administration account independent of network authentication.
XML Example:
<identityProviderMetadataUrl>[URL_to_metadata_by_saml_provider_here]</
identityProviderMetadataUrl>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
</globalRoles>
</autocreate>
</saml>
<oauth2 id="example2">
<authorizeUrl>https://accounts.google.com/o/oauth2/v2/auth</
authorizeUrl>
<tokenUrl>https://oauth2.googleapis.com/token</tokenUrl>
<clientId>[Your_client2_ID_here]</clientId>
<clientSecret>[Your_secret2_here]</clientSecret>
<mapping>
<id>sub</id>
<name>name</name>
<email>email</email>
</mapping>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
</globalRoles>
</autocreate>
</oauth2>
<oauth2 id="example3">
<authorizeUrl>https://github.com/login/oauth/authorize</
authorizeUrl>
<tokenUrl>https://github.com/login/oauth/access_token</tokenUrl>
<userUrl>https://api.github.com/user</userUrl>
<clientId>[Your_client3_ID_here]</clientId>
<clientSecret>[Your_sercet3_here]</clientSecret>
<responseParser>jsonpath</responseParser>
<mapping>
<id>$.id</id>
<name>$.name</name>
<email>$.email</email>
<description>$.bio</description>
</mapping>
<autocreate>
<enabled>false</enabled>
</autocreate>
<view>
<text>Legacy users</text>
</view>
</oauth2>
</authentication>
1. The username and password fields are hidden on the logon dialog (so users can't log on via local
password or LDAP). Users can authenticate via an SSO provider (SAML or OAuth 2). LDAP is only used
to authenticate electronic signatures.
In this case, the XML contains one or more <ldap> section(s), but no <password> section, and the
authentication method(s) that you want to use LDAP as an alternative electronic signature method
for, contain the forceLdapEsignatures="true" attribute in the main tag.
(The logon dialog box does not contain username and password fields or is skipped if your
configuration only contains a single logon option.)
XML Example:
<mapping>
<id>uid</id>
</mapping>
</ldap>
<oauth2 id="Oauth_example" default="true"
forceLdapEsignatures="true">
<authorizeUrl>https://accounts.google.com/o/oauth2/v2/auth</
authorizeUrl>
<tokenUrl>https://oauth2.googleapis.com/token</tokenUrl>
<clientId>[Your_client_ID_here]</clientId>
<clientSecret>[Your_secret_here]</clientSecret>
<mapping>
<id>sub</id>
<name>name</name>
<email>email</email>
</mapping>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
</globalRoles>
</autocreate>
</oauth2>
<saml id="Saml_example">
<identityProviderMetadataUrl>[Your_url_to_metadata_by_provider_here]</
identityProviderMetadataUrl>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
</globalRoles>
</autocreate>
</saml>
</authentication>
Note
If the records for the same userID exist for the local password and the LDAP (or LDAP servers), then
the order of the <password> and <ldap> sections in the XML file matters.
Note
• Combining <password> with <ldap> is independent of additional authentication methods.
(You can also add an unlimited number of <saml> or <oauth2> configurations to your XML
configuration.)
• Any of the <saml> or <oauth2> sections can use the LDAP as an alternative authentication for
eSignatures by adding the forceLdapEsignatures="true" attribute in their tag.
(You can also add an unlimited number of <saml> or <oauth2> configurations to your XML
configuration.)
XML Example:
icaj6v7gnelb1qggd2t26qvlibhadri5.apps.googleusercontent.com</clientId>
<clientSecret>Dl00JjDrrah5ldGgvLbq5p1H</clientSecret>
<mapping>
<id>sub</id>
<name>name</name>
<email>email</email>
</mapping>
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
</globalRoles>
</autocreate>
</oauth2>
</authentication>
You can configure authentication so that users can select an authentication method. (Provided that the
authentication providers have a record for the same userID.)
You do this in Polarion in the following two ways. (Depending on the number of users you want to
configure.)
c. Select/deselect providers under the Allowed Authentication Providers section and click
Save.
(Repeat this process for all of your target users.)
2. For user groups or when adding a new authentication provider:
b. Paste your provider XML formatted like the example below into the editor and click Save
Caution
Do not change a provider's id in the authentication.xml file once you've configured it.
If you feel you must, instruct your users to restart their browsers and update it in the XML at:
If you only want to adjust how a provider's name displays on user profiles in the Allowed Authentication
Providers section (and on the button on the log-on dialog box), then use the <view> tag in any of your
<saml> or <oauth2> sections.
XML Example:
Tip
You can also customize the icon in the button for SAML and OAuth 2 providers.
Tip
• If you use Polarion's internal XML editor (described below), the changes take effect when you save.
• If you update the login-id-configuration.xml file outside Polarion's internal XML editor, you must
restart Polarion.
Procedure
Tip
• You can add as many users as needed but cannot add multiple configurations for a single
Polarion user.
• Once migrated, your users should only use their new credentials.
Note
• Users must already exist in Polarion.
• You can configure LDAP, OAuth , SAML or Password login IDs for existing Polarion users.
• You can find defined login IDs under Users in Administration. ( Administration
User Management Users)
• Direct repository access is only possible with the original (Polarion) user ID.
Access Tokens are a widely adopted alternative to password authentication when integrating third-party
applications, and you can use them in Polarion to authenticate Web Services.
Caution
Access Tokens provide access to sensitive user information, so store them safely to protect them from
unauthorized exposure.
Note
Polarion Rest API calls are authenticated via JSON Web Tokens (JWT). (Currently, only personal access
tokens based on JWT are supported.)
Access Tokens are individually created and tied to the Polarion user that makes them. Users can manage
them within the Polarion UI, where they have complete control over their lifespans. Access Tokens
are easy to create and can be revoked at any time. (Instead of changing and potentially exposing user
passwords.)
Token-based authentication gives you an additional layer of security, making it harder for attackers to gain
unauthorized access.
Procedure
Tip
• System administrators can specify the maximum allowed time (in days) in the
com.siemens.polarion.security.personalAccessToken.maxDaysBeforeExpiry
property in the polarion.properties file. (The default value is 90 days.)
• We recommend a value between 90 and 180 days.
Caution
Click to copy this token to the clipboard, paste it into a new file and store it in a secure location.
(You will not be able to access it again.)
What to do next
You can terminate the validity of existing tokens before their expiration date by revoking them within the
Tokens section.
Procedure
Users must have the READ CONFIGURATION permission on the global level to enter Administration and
the Manage Users permission to manage personal access tokens for other users. The tokens can then be
used for any application that requires access to Polarion via an external API.
If you have Administrative rights and the Manage Users Global permission you can:
• Create a token for another user.
• View or revoke a user's token.
Note
If an administrator deletes a user, then all of the user's tokens are invalidated and deleted.
6. Click and enter an Expires on date. (Or enter a date in the following format 2023-12-25.)
Tip
The expiry date can be at most 90 days in the future.
Caution
If you do not copy the token now, you will not be able to view it again.
9. Press Ctrl+C to copy the token to your clipboard and paste it somewhere secure.
10. Close the Copy to Clipboard dialog box or click Cancel.
6. Click OK.
Administrators with the MANAGE USER permission can renew expired or soon-to-expire tokens of other
users.
6. Click OK.
A renewal confirmation appears and the Token's Created and Expires dates are updated.
Note
Administrator's can set the renewal period with the following property in the polarion.properties file:
com.siemens.polarion.security.personalAccessToken.maxDaysBeforeRenewedTokenExpi
(The default value is 90 days.)
Possible reason for failure:
If the value you set for the property above exceeds the value for the property below, tokens will fail to renew
com.siemens.polarion.security.personalAccessToken.maxDaysBeforeExpiry
To authenticate to SOAP WebServices, call the logInWithToken() method (part of Session Web
Services), with the following parameters:
• mechanism=AccessToken
• token=<YOUR-ACCESS-TOKEN>
• username=<IGNORED-KEEP-EMPTY>
Example
The request body should look like this:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ses="http://ws.polarion.com/SessionWebService-impl">
<soapenv:Header/>
<soapenv:Body>
<ses:logInWithToken>
<ses:mechanism>AccessToken</ses:mechanism>
<ses:username></ses:username>
<ses:token>***ACCESS-TOKEN-HERE***</ses:token>
</ses:logInWithToken>
</soapenv:Body>
</soapenv:Envelope>
In response, users receive a valid session ID in the header that's used to communicate with Polarion.
Note
The following code snippet represents a basic access token authentication workflow for Java applications
WebServiceFactory wsf;
try {
} catch (MalformedURLException e) {
return;
sessionService.logInWithToken("AccessToken", null, “
<yourPersonalAccessToken>”);
// credentials approach
// sessionService.logIn("user", "pass");
if (project == null) {
return;
}
…
To access the Polarion REST API, you can issue an HTTP request using JavaScript while within an active
Polarion session without having to generate a Personal Access Token (PAT). This means you can fetch data
from the API without needing a PAT.
Note
You must configure REST API Endpoint permissions before users can call REST endpoints.
To authenticate through the Polarion REST API, you can use the X-Polarion-Rest-Token header, which is
bound to the authenticated session and follows the same lifecycle.
(This means you don't need to supply a PAT when making API calls.)
The generated X-Polarion-REST-Token is valid only for the current session and becomes invalid once the
user logs out.
Tip
This feature is useful in Report Page widgets, where you can fetch data on demand.
To use the X-Polarion-REST-Token, add the following property to the polarion.properties file:
com.siemens.polarion.rest.security.restApiToken.enabled=true.
Caution
The Polarion REST API using the X-Polarion-REST-Token can perform read/write operations on behalf of
the user viewing a Polarion Report Page. Therefore, ensure that write Page permissions are defined
correctly and only enabled for trusted users to prevent malicious scripts from running on users without
their knowledge.
To authenticate your Polarion REST API call, supply the X-Polarion-REST-Token header in each Polarion REST
API request.
The value of the header is obtained from the window.getRestApiToken() function, which generates
the session-bound token.
<script>
// declaration
function fetchRestAPI(resource, options) {
var restToken = top.getRestApiToken();
if (options == undefined) {
options = {};
}
if (options.headers == undefined) {
options.headers = new Headers();
}
if (options.headers instanceof Headers) {
options.headers.set("X-Polarion-REST-Token", restToken);
options.headers.set("Accept", "application/json");
} else {
options.headers["X-Polarion-REST-Token"] = restToken;
options.headers["Accept"] = "application/json";
}
return fetch(resource, options);
}
// invocation
fetchRestAPI("/polarion/rest/v1/projects/drivepilot/workitems/DP-584")
.then(response => {
console.log("fetchRestAPI response: ", response);
if (!response.ok) {
throw new Error('HTTP error! Status: ${response.status}');
}
return response.json();
})
.then(json => {
console.log("fetchRestAPI json: ", json);
});
</script>
Advanced configuration
When planning your user authentication configuration, there can be considerations beyond just setting
up the authentication configuration itself. There can also be ramifications for different Polarion features
or functionality. Some things may require some additional configuration to work with your authentication
scheme, some may not support it, or may have some limitations.
Be sure to go through the topics in this section to assess their relevance for your system.
Configuration file location How to change the default location of the authentication configuration
file (not recommended for most cases).
Add an icon to a provider You can add custom icons to SAML and OAuth 2 provider logon buttons.
logon
Auto-create user accounts Configure your authentication to automatically create Polarion user
accounts for new users the first time they log on.
Enable "Create your Polarion Configure authentication so that users can self-register and create their
account" link own Polarion account.
Direct SVN access How to configure authentication for direct access to the Subversion
repository (by external clients, or scripts, for example).
Electronic signatures Some authentications need some additional configuration if your users
will need electronic signatures for Documents, Work Items and Test Runs.
License allocation Control how license are allocated when users log on or new users are
created via different authentication methods or providers.
Logon dialog box size Adjust the size of the internal logon dialog box.
Resource Traceability Information on authentication for systems where the Resource
Traceability feature will be used.
Secure secrets storage Information about setting up and customizing secure secrets storage.
LDAP tips and tricks General tips and tricks for configuring and synchronizing LDAP with
Polarion.
Synchronize users with LDAP How to synchronize user accounts with an LDAP server.
Synchronize user Groups Assign users to Groups automatically via LDAP synchronization.
with LDAP
Synchronize user Groups Assign users to Groups automatically via SAML synchronization.
with SAML
Reserved XML characters What characters are reserved for XML and how to use them in the
authentication.xml tags.
Fallback authentication for Information on configuring authentication to work with web services.
Web services
Recover from a Some tips on avoiding a lockout and how to recover from one if it
misconfigured XML happens.
Retrieve SAML metadata via Retrieve the SAML metadata required to interact with SAML-enabled
servlet identity or service providers.
Internal log-on pop-up In case of SAML SSO and TeamCenter SSO the logging process is
behavior redirected to the IdP log-on or the Team Center Log-on. Since it may
be a security issue to embed the log-on page in the internal log-on popup
IFrame, by default, TC and SAML SSO have internal log-on in IFrame
disabled.
As of Polarion 21 R1, the authentication.xml file is where you configure Polarion authentication.
(Kerberos is the exception. You must configure it via properties in the polarion.properties file.)
Warning
• If you create/update the authentication.xml file outside of Polarion's UI, changes do not propagate to
the Authentication section in Administration.
(Likewise, if users make changes via the Authentication section of Polarion, they'll override any
externally created authentication.xml file.)
• If you create this file directly outside of Polarion's UI, you must set the file ownership and file
permissions so that Polarion (via the "polarion" user) can read and write to it.
• If you create/update this file directly, you must restart the Polarion service for your changes to take
effect.
• If you create/update this file directly, and it contains syntax errors, the starting of the Polarion service
might hang.
To fix it, just correct the file's syntax and save it. (The starting process will continue automatically.)
• If you create/update this file directly, you must restart the Polarion service for your changes to take
effect.
If you access and edit the file within Polarion (recommended) the built-in XML editor prevents syntax errors
that would result in a broken configuration.
Default locations:
Linux: /opt/polarion/data/authentication
Windows: \Polarion\data\authentication
You can set your own location for your authentication.xml file by entering the full path (including your
custom filename) to the file in the following property in the polarion.properties file.
com.siemens.polarion.security.auth.file=/[your_path_to_file]
Default locations:
For Cluster setup, the file is stored on the Coordinator under the $POLARION_DATA/workspace/cluster-data
folder.
You can set a custom folder location to your authentication.xml file in a Cluster by entering the following
in the polarion.properties file on the Coordinator machine.
com.siemens.polarion.security.auth.cluster.folder=/[your_path_to_folder]
[your_path]/$cluster_id/authentication/authentication.xml
(Where cluster_id is the ID of the specific installation. This hierarchy is created, if required, when you click
Save on the Authentication administration page in Polarion.)
This will propagate files from the Coordinator to all nodes before they start and on every change.
You can add custom icons or replace the default SSO provider icons on the login buttons.
Custom button icons are possible for SAML and Oauth 2 SSO providers.
Tip
The recommended icon size is 32px by 32px and some examples are listed at the end of this section.
You can change the default logo (the diamond logo in the image above), if you have a single provider or
want the same logo to appear for all configured providers.
Procedure
If not configured otherwise, the <saml> or <oauth2> sections configured in your authentication.xml
now appear on the login screen with this icon. (To access the authentication.xml configuration file, Go
to Global Administration if you're in a project, or Administration if you're working in the Default
Repository. In Navigation, expand User Management and select Authentication.)
You can change the logo for any configured SSO provider separately.
Procedure
<view>
<text>YOUR-CUSTOM-PROVIDER-NAME-HERE</text>
<icon>[IMAGE PATH / URL / OR OUT OF THE BOX ICON NAME]</icon>
</view>
Note
The <text> tag is optional and can be omitted here.
4. Enter the desired value in the <icon> tag. See the Choose the icon value section below for the
correct value format.
You can choose one of the following three sources for the icon value:
Procedure
1. Use a full URL that points to the icon. (URL must be accessible by Polarion.)
2. Use the name of one of the provider icons that Polarion provides out of the box.
• auth0 (for Auth0)
• azuread (for Azure Active Directory)
• facebook (for Facebook)
• github (for GitHub)
• google (for Google)
• linkedin (for LinkedIn)
• microsoft (for Microsoft)
• pingidentity (for Ping Identity)
3. Add a custom icon to the following directory on the server and use the path and image name.
[POLARION_HOME]/polarion/plugins/com.polarion.alm.ui_N.NN.N/webapp/ria/images/logos/
[yourimage.png]
(Where N.NN.N is the Polarion version number like 3.21.2)
Examples
• To display the default icon for a SAML identify provider, the <saml> section in the authentication.xml
file should be as follows:
<saml id="ID-OF-YOUR-SSO-HERE">
<identityProviderMetadataUrl>YOUR-URL-HERE</
identityProviderMetadataUrl>
...
</saml>
Note
No <view> section is required here.
• To display a custom icon with a publicly available URL for a SAML identity provider, the <saml> section
in the authentication.xml file should be as follows:
<saml id="ID-OF-YOUR-SSO-HERE">
<identityProviderMetadataUrl>YOUR-URL-HERE</
identityProviderMetadataUrl>
<view>
<icon>https://about.gitlab.com/ico/favicon-32x32.png</icon>
</view>
...
</saml>
Note
In this case, the button’s label is the text in the id= attribute.
• To display one of the custom icons provided out of the box for an OAuth 2 authorization server, the
<oauth2> section in the authentication.xml file should be as follows:
<oauth2 id="ID-OF-YOUR-SSO-HERE">
<authorizeUrl>YOUR-AUTHORIZE-URL-HERE</authorizeUrl>
<tokenUrl>YOUR-TOKEN-URL-HERE</tokenUrl>
<clientId>YOUR-CLIENT-ID-HERE</clientId>
<clientSecret>YOUR-CLIENT-SECRET-HERE</clientSecret>
<view>
<icon>auth0</icon>
<text>YOUR-CUSTOM-NAME-HERE</text>
</view>
</oauth2>
Note
◦ The button displays the auth0 icon that's provided out of the box.
◦ The button’s label is the text provided in the <text> tag.
• To display a custom icon stored somewhere in Polarion's repository for a SAML identity provider, the
<saml> section in the authentication.xml file should be as follows:
<saml id="ID-OF-YOUR-SSO-HERE">
<identityProviderMetadataUrl>YOUR-URL-HERE</
identityProviderMetadataUrl>
<view>
<icon>/polarion/ria/images/logos/small/logo.png</icon>
<text>YOUR-CUSTOM-NAME-HERE</text>
</view>
</saml>
Note
The button displays the icon stored at [POLARION_HOME]/polarion/plugins/
com.polarion.alm.ui_N.NN.N/webapp/ria/images/logos/logo.png]
The Auto-create feature makes it possible to create user accounts for new users the first time they log
on to Polarion, with LDAP credentials or via an SSO identity provider. New users created this way are also
assigned the user role(s) configured for new auto-created users.
It is recommended to configure the Auto-create feature with at least a role that enables users to log on -
the user role, for example. Be sure you understand the roles and the permissions they grant to users, and
recommended best practice for role assignments. For information, see Default Roles and Permissions.
Tip
In cases where more than one license is present on the server, it is also possible to configure which
license type is allocated to new auto-created users. This is always configured in the polarion.properties
file.
The way your set up the Auto-create configuration differs depending on whether your authentication
configuration is implemented in authentication.xml or using configuration properties set in
polarion.properties.
If you need your configuration to support multiple LDAP, SAML, and OAuth 2 authentication providers
configured simultaneously, you must configure Auto-create separately for each one.
To enable auto-create for a particular provider, insert the <autocreate></autocreate> section into
the provider's definition in authentication.xml. Inside the section you can specify a list of global roles to be
assigned to newly auto-created users.
(See the method-specific topics under Configure a new installation Overview for examples.) The
section typically looks like this:
<autocreate>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
<role>custom_global_role</role>
</globalRoles>
</autocreate>
Tip
• The list of roles can be different for each authentication provider with enabled auto-create.
• Please be aware that the global Administration page User Management > Auto-create (mentioned in
the section below) no longer appears in Navigation after adopting authentication.xml, because those
options are now set in the XML configuration.
• Looking to limit users authenticating via IdP that can Auto-create Polarion accounts? Use the
<entitlements> and <userClaim> tags.
Note
This is mostly applicable to Kerberos that is not supported in the authentication.xml file. (Please see the
method-specific topics for these methods for details.)
It may also be applicable to other authentication methods, typically after updating from version older
than 21R1, before adopting authentication.xml to configure user authentication.
If authentication.xml is not used for user authentication, Auto-create can be configured in global
Administration.
Procedure
1. Log on with administrator permissions for the repository. Enter global Administration if you are not
already there after logging on.
2. In Navigation, expand User Management and select Auto-create. (If this node does not appear, it
means that authentication.xml is present on your system.)
3. On the Auto-create page, select Enable Auto-create.
The Global Roles list appears. The user role is selected by default.
4. Specify the global (repository-scope) role(s) to automatically apply to all auto-created user accounts.
You can configure authentication so that users can self-register and create their own Polarion account
using a Create your Polarion Account link on the Polarion logon dialog box.
When users click the link, a form appears that lets them specify account credentials, including user name,
password, and an email address for receiving notifications. When the form is submitted, the log on page
appears again and they can log on with the new credentials. They are also assigned the role(s) configured
for newly registered users. We recommend that you configure the feature with at least one role that
enables users to log on. (For example, the user role.) Make sure that you understand the roles (and the
permissions that they grant) and follow the suggestions outlined in Default Roles and Permissions.
You can configure self-registration in the authetication.xml for password authentication by adding the
following:
<password>
<registration>
<enabled>true</enabled>
<globalRoles>
<role>user</role>
</globalRoles>
</registration>
</password>
Tip
• You can also specify the minimum length for passwords in the minimalPasswordLength property
in the polarion.properties file.
• To change the default size of the dialog box, see Logon dialog box size.
All primary Polarion data is stored in the Subversion repository. To ensure the traceability of commits to
their authors, the ability to write to the Subversion still needs to be subject to authentication, even when
SSO authentication is used with Polarion.
We recommend that you only access SVN via Polarion. If you want to access SVN via Polarion and
directly via a web browser or SVN client like Tortoise, you must reconfigure your setup and add a new
<Location/> for direct, external access.
The new Location for direct SVN access should be authenticated against the passwd_credentials file.
File location
• For Linux:
The file location may differ depending on your Linux distribution. Typically it is:
By default, the polarionSVN.conf file will be defined with the following that gives Polarion access to SVN:
• <Location /repo>
It's checked against the password file that you define in the following AuthUserFile section.
• AuthUserFile: [Polarion_Home]/data/svn/passwd
Note
Accessing SVN via an external tool is no longer recommended.
We recommend that you only access SVN via Polarion. If you want to access SVN via Polarion and
directly via a web browser or SVN client like Tortoise, you must reconfigure your setup and add a new
<Location/> for direct, external access.
• You need two <Location/> sections in your Apache configuration. One used by Polarion and
authenticated against the passwd file. The other is for direct SVN access and authenticated against
the passwd_credentials file. You can name the <Location/> sections whatever you want.
Tip
The difference between the password files mentioned above:
◦ passwd_credentials
Only contains the local passwords known by local users. You can reference this file to access the
SVN directly via third-party clients.
◦ Passwd
It stores system-generated secrets for internal Polarion processes.
It is used exclusively by Polarion to grant SVN access to all users. (SSO users, local users, LDAP users,
etc.)
Any changes to this file will be overwritten by Polaron's internal processes anyway.
• If you already have a lot of dependencies (users, tools) on the original /repo location, it will be
probably easier to keep and adjust the existing/repo for the external dependencies and create a new
<Location/> pointing to the generated passwd file that will be used by Polarion.
Procedure
Examples
To access the SVN repository directly via a web browser or an SVN client like Tortoise:
<Location /[your_custom_label]>
DAV svn
SVNPath "[Polarion_Home]/data/svn/repo"
SVNAutoversioning on
AuthzSVNAccessFile "[Polarion_Home]/data/svn/access"
Require valid-user
AuthType Basic
AuthName "Subversion repository"
AuthUserFile "[Polarion_Home]/data/svn/passwd_credentials"
</Location>
<Location /repo>
DAV svn
SVNPath "[Polarion_Home]/data/svn/repo"
SVNAutoversioning on
AuthzSVNAccessFile "[Polarion_Home]/data/svn/access"
Require valid-user
AuthType Basic
AuthName "Subversion repository"
AuthUserFile "[Polarion_Home]/data/svn/passwd"
</Location>
If you must have the default (/repo) location accessible externally (for example, to preserve an existing
configuration for external tools), you should reverse the configuration from the example above and adjust
the polarion.properties file to use the other repo location.
Procedure
Tip
(You can name it anything you want. For example, /repo-internal)
3. Open the polarion.properties file and set the repo= property to point to the newly created custom
location and save your changes.
(For example <YOUR_URL>/repo-internal/ using the custom name created above.)
Here is how you can configure the polarionSVN.conf file to allow direct access for both local and LDAP
users.
Note
• The default polarionSVN.conf file only has a single internal repository location.
• The procedure below shows how to add two external repository locations.
(You can rename them whatever you want but they are repo_access_ldapUser and
repo_access_localUser in the example below.)
• You can remove one if you do not need both.
• Consider limiting direct access to responsible users and be mindful of unsupported changes to the
repository.
Procedure
1. Locate the internal repository location. (You can find it in the <Location /repo> tag in the
authentication.xml file.)
This location is used by Polarion and authentication is managed by the authentication.xml file. No
changes are needed here.
Note
• If you are updating from a Polarion version older than 21 R1, just copy over the Active Directory
LDAP configuration section from the polarionSVN.conf file.
• Otherwise, you can extract it from the authentication.xml file but the syntax differs.
• You should trim the LDAP query to limit direct access to only responsible users. They require both
READ and WRITE permissions.
• Direct changes to the repository are unsupported. (See the example below.)
3. Now you must configure the optional external repository location for local users.
(It is set in the <Location /repo_access_localUser> tag of the authentication.xml file.)
Its authentication is controlled by a hashed password stored in the passwd_credentials file.
(No LDAP configuration is needed for this and no hashed passwords are needed for LDAP
authentication.)
Recommendation: Limit direct access to responsible users, because this is not officially supported.
(See example below.)
This example configuration contains hard-coded paths to server files that may not be correct for your
operating system and Polarion installation.
Caution
Adjust the paths to match those found in your original polarionSVN.conf file and update as needed.
• Windows: C:\Polarion\bundled\apache\conf\extra\
• Linux: /etc/httpd/conf.d/
(The example below contains the paths for a Windows installation and will not work on Linux)
SVNPath "C:/Polarion/data/svn/repo"
AuthzSVNAccessFile "C:/Polarion/data/svn/access"
AuthUserFile "C:/Polarion/data/svn/passwd"
AuthUserFile "C:/Polarion/data/svn/passwd_credentials"
<IfModule !mod_dav.c>
LoadModule dav_module modules/mod_dav.so
</IfModule>
<IfModule !mod_dav_fs.c>
LoadModule dav_fs_module modules/mod_dav_fs.so
</IfModule>
<IfModule !mod_dav_svn.c>
LoadModule dav_svn_module modules/mod_dav_svn.so </IfModule>
<IfModule !mod_authz_svn.c>
LoadModule authz_svn_module modules/mod_authz_svn.so
</IfModule>
<IfModule !mod_ldap.c>
LoadModule ldap_module modules/mod_ldap.so
</IfModule>
<IfModule !mod_authnz_ldap.c>
LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
</IfModule>
<IfModule mod_dav_svn.c>
#Caching configuration for Subversion performance optimization:
#For more details read the "Subversion cache memory" section of the
"Configure and optimize Subversion"
#chapter in the Polarion installation documentation for Windows.
#Available on Support Center: https://polarion.plm.automation.siemens.com/
documentation/latest.
SVNInMemoryCacheSize 131072
#If Subversion is on localhost you may want to disable the compression to
conserve CPU resources
SVNCompressionLevel 0
<Location /repo>
#Enable Web DAV HTTP access methods DAV svn
#Repository location
SVNPath "C:/Polarion/data/svn/repo"
#Write requests from WebDAV clients result in automatic commits
SVNAutoversioning on
#Our access control policy
AuthzSVNAccessFile "C:/Polarion/data/svn/access"
SVNPathAuthz short_circuit
#No anonymous access. Always require authenticated users
Require valid-user
#How to authenticate a user. (NOTE: Polarion does not currently support
HTTP Digest access authentication.)
AuthType Basic
AuthName "Subversion repository"
AuthUserFile "C:/Polarion/data/svn/passwd"
<IfModule mod_authnz_ldap.c>
#Authenticate against file if authentication.xml does not exist at update.
AuthBasicProvider file
</IfModule>
</Location>
<Location /repo_access_ldapUser>
#Enable Web DAV HTTP access methods
DAV svn
#Repository location
SVNPath "C:/Polarion/data/svn/repo"
#Write requests from WebDAV clients result in automatic commits
SVNAutoversioning on
#Our access control policy
AuthzSVNAccessFile "C:/Polarion/data/svn/access"
SVNPathAuthz short_circuit
#No anonymous access. Always require authenticated users.
Require valid-user
#How to authenticate a user. (NOTE: Polarion does not currently support
HTTP Digest access authentication.)
AuthType Basic
AuthName "Subversion repository"
#To enable authentication against LDAP:
#Ensure that modules mod_authnz_ldap and mod_ldap are loaded: uncomment
#Corresponding LoadModule directives at the beginning of this file
#Uncomment LDAP options below
#Documentation of used LDAP module and its parameters (for Apache 2.4.x) is
available at
#http://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html
#http://httpd.apache.org/docs/2.4/mod/mod_ldap.html
<IfModule mod_authnz_ldap.c>
#Authenticate against LDAP
#Allows you to combine Polarion-only users with organization-wide users.
AuthBasicProvider ldap
#Active Directory
AuthLDAPURL "ldap://DECGNVVCLOUDDC1.cgnvcloud.local:389/ou=vCloud-
Users,dc=cgnvcloud,dc=local?sAMAccountName?sub?(objectclass=user)"
AuthLDAPBindDN "cn=infodba,ou=vCloud-Users,dc=cgnvcloud,dc=local"
AuthLDAPBindPassword "password"
#Uncomment this when "500 Server failed" is returned and Apache's log
contains the following error.
#"This function has not been implemented on this platform: AH01277: LDAP:
Unable to add rebind crossreference entry. Out of memory?"
LDAPReferrals Off
</IfModule>
</Location>
<Location /repo_access_localUser>
DAV svn
SVNPath "C:/Polarion/data/svn/repo"
SVNAutoversioning on
AuthzSVNAccessFile "C:/Polarion/data/svn/access"
SVNPathAuthz short_circuit
Require valid-user
AuthType Basic
AuthName "Subversion repository"
AuthUserFile "C:/Polarion/data/svn/passwd_credentials"
</Location>
</IfModule>
Electronic signatures
Under normal circumstances, with Single Sign-on (SSO), users do not have to enter their credentials
anywhere in Polarionif they’ve logged on to an associated SSO account. Electronic signatures are an
exception. Unless you are using the SAML or OAuth 2 standards for SSO authentication, an alternative
LDAP connection needs to be configured.
Note
You can use Electronic signatures throughout Polarion. Please refer to the following for information on
how to configure them.
• When SAML/Oauth 2 are used for authentication, users can sign via SAML/Oauth 2, or alternatively via
LDAP.
• If your organization uses SAML/OAuth 2 SSO authentication, you do not need to configure LDAP, but if
you want to use LDAP along with them you can.
• To configure OAuth 2 for electronic signatures you must also set the redirect URL in your authentication
provider's IdP configuration and electronic signatures configuration settings as follows:
• Polarion's password authentication, or LDAP authentication can be used for signing "out-of-the-box".
Note
If forceLdapSignatures=true is configured in the authentication.xml file then LDAP is used
instead.
Procedure
1. Make sure that the LDAP Server Connection is configured and the authentication.xml file contains
the appropriate <ldap> section.
(See LDAP tips and tricks for more information, LDAP on a new installation for examples, and the
LDAP-technical reference section.)
2. Define which of the SAML or OAuth2 configuration(s) should use LDAP as an alternative for
eSignatures. You do so by adding the forceLdapEsignatures="true" attribute in the leading
tag of the appropriate <saml> or <oauth2> section in the authentication.xml.
Note
• Since Polarion 21 R1 you can define which of your <saml> or <oauth2> providers use the LDAP
as a fallback for eSignatures independently per provider.
• If your configuration has multiple LDAP configurations, you can't limit which is used for
eSignature authentication.
However, for multiple <ldap> sections in the authentication.xml, their order matters.
• If you only want to allow your users log on to Polarion via SSO (SAML or Oauth2), and you
don't want to allow them to log on via a local password or LDAP, you can hide the username
and password fields on the log on dialog box by removing the <password> section from
your authentication.xml file. (See the Use provider logon and Combine multiple providers
sections.)
Caution
Administrators must ensure that the user who signs via LDAP and logs on via SSO has identical IDs
on both sides.
Configuration example
• The LDAP configuration is configured to authenticate eSignatures, but users can't log on via LDAP.
• One SAML configuration uses LDAP for eSignatures.
• One SAML configuration uses SAML for eSignatures.
<ldap id="ldap_for_eSignatures_but_not_for_logon">
<url>ldap://ldapprovider.example.com:389</url>
<baseDn>OU=users,DC=example</baseDn>
<bindDn>CN=binduser,OU=users,DC=example</bindDn>
<bindPassword>[Your_password_as_plain_text_here]</bindPassword>
<mapping>
<id>sso_id</id>
</mapping>
</ldap>
<saml id="Saml1_does_eSignatures_by_ldap" default="true"
forceLdapEsignatures="true" >
<identityProviderMetadataUrl>https://provider1.example.com/sso/saml/
metadata</identityProviderMetadataUrl>
</saml>
<saml id="Saml2_does_eSignatures_by_saml" >
<identityProviderMetadataUrl>https://provider2.example.com/sso/saml/
metadata</identityProviderMetadataUrl>
</saml>
<oauth2 id="oauth_does_eSignatures_by_ldap" forceLdapEsignatures="true">
<authorizeUrl>https://oauthprovider.example.com/authorize</authorizeUrl>
<tokenUrl>https://oauthprovider.example.com/oauth/token</tokenUrl>
<clientId>[Your_client_id_here]</clientId>
<clientSecret>[Your_secret_here]</clientSecret>
</oauth2>undefined</authentication>
You can control how licenses are allocated when users log on, or new user accounts are created via
different authentication methods or providers.
• named
• concurrent
• concurrentGroup
[FEATURE-SET] may vary according to the current Polarion licenses available. It will be something like
QA, ALM, REQUIREMENTS, REVIEWER, etc. To find the licenses currently on your system, open global
Administration, and in Navigation select License.
Examples:
• licenseForNewUserAccount=namedALM
• licenseForNewUserAccount=concurrentQA
• licenseForNewUserAccount=concurrentGroupREVIEWER
Note that if concurrent license groups are defined in the global configuration, it is possible to specify
a concurrent license group in the licenseForNewUserAccount property rather than a license. For
information on these groups, see the embedded Quick Help in the License page of global Administration.
If no value is specified in the property, the user will get the first available "lowest" license - that is, the
most restrictive. For example, if no free concurrent slots are available, Polarion will try to allocate a named
license, and so on. After that it will go from fewest features (currently REVIEWER), incrementally towards
full features (currently ALM), depending on what slots are available.
Administrators can optionally adjust the pixel dimensions of the internal logon dialog box. This may be
needed when using a third-party authentication method (typically Teamcenter Security Services).
The size can be adjusted by adding the following properties to the polarion.properties file (or adjusting the
dimension values if the properties are already present in the file).
Resource Traceability
You must do the following to use a Polarion repository with an external password as the Resource
Traceability repository.
Tip
See Polarion repository andResource Traceability for more information.
The authentication.xml file contains the passwords for LDAP connections, or the client-secrets for OAuth 2
connections.
If you want to store the passwords and secrets securely, you can keep them in the User Account Vault.
Note
The following table compares how you configure the authentication.xml file for either plain-text
secrets, or secrets stored in the User Account Vault.
<ldap> <ldap>
<bindPassword
<bindPassword>passwordExample1</ userAccountVaultKey="KeyExample1"/>
bindPassword>
… …
</ldap> </ldap>
Tip
See Access Token support to authenticate Web Services.
There are two ways you can update the secrets stored in the User Account Vault.
• Update the account in Polarion via the User Account Vault by adding a userAccountVaultKey
• Update the vault record via SOAP Web Services
Update the account in Polarion via the User Account Vault by adding a userAccountVaultKey.
Procedure
2. Enter a key name (for example, myLdapBindPwd) in the Key field and the username in the User
Name field.
(The User Name can be any string. It will be ignored. Only password matters. )
3. Enter the password twice, click on the right and Save on the top left.
4. Now refer to this secret value in your LDAP configuration instead of exposing it as plain text and
Save.
(Somewhere within the <ldap> tags like the following:)
</ldap>
Procedure
• Update the vault record manually from Global Administration User Management
User Account Vault
• Update the vault record via Soap Web Service calls. (This can be automated via scripts)
In both cases, changes are immediately applied and there's no need to resave the XML configuration or
restart Polarion.
Here you'll find general tips and tricks for configuring and synchronizing LDAP with Polarion.
Note
If your Apache configuration has LDAPReferrals set to Off, when you migrate your authentication
configuration to the authentication.xml file implemented in Polarion 21 R1 users might experience
performance slowdowns when they log on. See If LDAPReferrals is set to "Off" to mitigate this.
You can let users automatically create their Polarion account when they first log on to Polarion via their
LDAP credentials.
Auto-create can be enabled in the authentication.xml file independently for each LDAP configuration by
adding an <autocreate> section. For more information see, Auto-create, the LDAP specific attributes
section and an XML example in LDAP for new installations.
User accounts configured in Polarion can be synchronized with a configured LDAP server. This lets you
update the details of user profiles, or import new users into Polarion in bulk.
• Synchronization can be enabled in the authentication.xml file independently for each LDAP
configuration by adding a <synchronization> section. For more information see the LDAP specific
attributes section and an XML example in LDAP for new installations.
• See Synchronize Users with LDAP for details on how to execute a Synchronization and create or
update existing account information in bulk.
You can assign users to your groups in Polarion automatically via LDAP synchronization.
• Your authentication configuration can contain multiple LDAP connections, but only one can be
configured to synchronize User Groups.
(By adding syncUserGroups="true" to an LDAP configuration in the authentication.xml file.)
• Each target group that you want to synchronize with LDAP must have an LDAP Search Filter to identify
the users that should belong to the group.
• By synchronizing User Groups with LDAP, users are automatically added to or removed from a group.
It lets you efficiently manage user roles to ensure that they align with your current organizational
structure.
For more details, please see Synchronize User Groups with LDAP and Querying Nested Groups below.
Tip
You can also Synchronize User Groups with a configured SAML provider.
The <baseDn> tag in the LDAP configuration in the authentication.xml file tells you what branch
of the LDAP directory structure you are trying to obtain the information about users from.
The <searchSubtree> tag tells if you want to obtain the information only from the specified
node in the tree hierarchy (using <searchSubtree>false</searchSubtree>), or if you want
to obtain the information gathered recursively from the whole sub-tree in the directory (using
<searchSubtree>true</searchSubtree>).
There are a few places in Polarion‘s administration where you can use LDAP Search Filters:
• In the LDAP configuration in authentication.xml file, you can set the <searchFilter> query to further
narrow the selection of users who can authenticate to Polarion via LDAP.
Composing Search Filter queries heavily depends on how the data are organized on the LDAP directory
side. For example, you can ask for members of some unit in an organizational structure. If the
organizational structure is more complex, Active Directory LDAP offers additional querying for the
members of a unit and the members of all its sub-units.
This "Nested Group Filtering" is a query syntax capability provided by Active Directory LDAP. (Other LDAP
providers may not support it.)
To use Nested Group Filtering, include the :1.2.840.113556.1.4.1941: string in your query with the
memberOf=… criteria.
Example
Nested Group filtering:
(&(objectCategory=Person)(sAMAccountName=*)
(memberOf:1.2.840.113556.1.4.1941:=cn=UserGroup,ou=Groups,ou=CompanyUsers,dc=test,d
Note
The 1.2.840.113556.1.4.1941 string specifies the LDAP_MATCHING_RULE_IN_CHAIN. (It only
applies only to DN attributes.) This extended match operator crawls the chain of ancestry in objects
to the root, uncovering nested groups until it finds a match. It is available only on domain controllers
with Windows Server 2003 SP2 or Windows Server 2008 (or above).
When composing an LDAP query you may need to compose a complex query to get what you really need.
You can use the AND (&) or OR (|) logical operators to further refine your query. This lets you synchronize
users from more than one LDAP group or from only part of a single LDAP group.
Examples:
• (&(displayName=*Andy*)(workSite=*Prague*))
Returns users whose displayName attribute contains Andy AND whose workSite attribute contains
Prague.
• (|(displayName=Andy)(displayName=George*))
Returns users whose displayName attribute matches exactly Andy OR whose displayName attribute
begins with George.
• (&(displayName=*Andy*)(!(workSite=*Bratislava*)))
Returns users whose displayName attribute contains Andy AND whose workSite attribute DOES
NOT contain Bratislava.
You can even use the is greater than or equal to (>=) and is less than or equal to (<=) operators instead of
the commonly used is equal to (=) operator where it makes sense:
• (|(badPasswordCount>=100)(memberOf=CN=Blocked
Users,CN=Users,DC=Company,DC=Root))
Returns users whose badPasswordCount attribute value is greater than or equal to 100 OR are
members of the CN=Blocked Users,CN=Users,DC=Company,DC=Root group.
• (&(badPasswordCount>=0)(!(badPasswordCount=0))(!
(memberOf=CN=Admins,CN=Users,DC=Company,DC=Root)))
Returns users whose badPasswordCount attribute value is greater than 0 AND are not members of the
CN=Admins,CN=Users,DC=Company,DC=Root group.
• The options in the <ldap> section of the authentication.xml file configure the set of user nodes that
are returned from LDAP to Polarion. The result is the intersection of a set of nodes below a base
node <baseDN>, that satisfies the search filter <searchFilter>, or optionally the whole
sub-tree <searchSubtree>true<searchSubtree/> and a set of nodes in an LDAP group
<groupDn> if it's specified.
Caution
When both the Search Filter and Group DN are used, querying takes significantly more time than when
just one of these option is used.
The authentication configuration can contain multiple <ldap> sections to connect Polarion with multiple
LDAP servers. Each configuration section can activate synchronization with its configured LDAP server
independently.
Related Topics
LDAP
LDAP
Note
• See the LDAP tips and tricks page and the LDAP technical reference section for information on how
to define user group Search Filters and other LDAP configuration attributes.
• The Synchronization can be enabled in the authentication.xml file independently for each LDAP
configuration by adding the <synchronization> section.
Procedure
1. Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure for LDAP
synchronization.
Tip
Looking to synchronize User Groups?
6. Click Synchronize
The synchronization process begins and an informative message appears.
To schedule a job that automatically synchronizes Polarion/LDAP users by adding the following to the
Scheduler.
• Synchronize Polarion the two configured LDAP providers every day at 7a.m.
• Synchronize new users.
• If current user information is out of sync, it's updated.
Tip
To run scheduled jobs at any time, go to the Monitor topic in Navigation, select the job and click
Execute Now.
Polarion can synchronize its User Groups with those supplied by SSO providers (ADFS, Azure, Okta, etc.)
over the SAML and OAuth 2 protocols. You can configure Group Synchronization so that it's performed
every time a user logs on to Polarion.
Synchronization is only one way. User Groups can be updated, created, or removed in Polarion based on
the information from SSO providers configured in the authentication.xml file, but changes in Polarion
User Groups do not get updated in the SSO providers.
Caution
SSO Group Synchronization is complex and must be done by carefully. Read up on and follow the steps
below before saving any configuration.
Procedure
1. Make sure that the system user has the required permissions.
2. Add the <groupsSynchronization> tag to the target SSO provider in your authentication.xml file.
3. Trace SSO provider responses, to help you to correctly configure the feature.
4. Claim scopes for OAuth 2 authorization servers. (If applicable)
5. Typically, the list of Groups is read from a single field, but you can also combine multiple lists
obtained from different fields.
6. Querying the received responses depends heavily on the implementation and configuration on the
SSO provider side.
7. For OAuth 2 you can select a parser to use. (If applicable)
8. You can include or exclude existing Polarion Groups from the SSO Group Synchronization
process.
9. Read up on the limitations before combining SSO Group synchronizations with manual Group
administration or LDAP Group Synchronization jobs.
SSO Group Synchronization requires that the system user (polarion by default) has read&write
permissions for the /.polarion/user-management/ folder in the repository.
Note
• New Polarion installations are ready for SSO Group Synchronization out of the box.
• Older Polarion installations updating to Polarion 21 R2 or higher, must set these permissions
manually.
Procedure
3. Click Edit.
4. Scroll down to Users Assignment and select Read & Write for the polarion user.
Warning
If SSO Group Synchronization is enabled and the system user does not have write permissions
for, under Users Assignment, any logon attempt that uses SSO synchronization will fail. (Users will
not be able to logon via SSO until it is fixed.)
Here are the steps required to enable Group Synchronization for an SSO provider.
Procedure
<groupsSynchronization>
<enabled>true</enabled>
<groupsMapping>
<namePath>YOUR_GROUP_LIST_NAME</namePath>
</groupsMapping>
</groupsSynchronization>
Tip
To temporarily disable Group Synchronization, set the <enabled> tag within the
<groupsSynchronization> tag to false.
SSO group synchronization can be a tricky beast to configure correctly without the proper tools. By default,
no details of the authentication flow and synchronization process are present in the logs, but you can use
some additional tools to get the information you need.
You can use SAML Tracers to sniff out the SAML Assertion message sent by your SAML Identity Provider.
If you are having trouble configuring your SAML provider, deploy a SAML Tracer to ensure that the SAML
Assertion sent to Polarion contains the correct information and is parsed correctly.
Tip
• Some Identity Providers require that you configure the scopes on their side in order to include the list
of User Groups as part of the SAML assertion message.
• The name of the attribute with the Group list in the SAML Assertion message depends on the
configuration on the provider side.
Administrators can temporarily allow verbose logging for the logon and Group Synchronization process.
Verbose logging is enabled by adding <traceSsoResponses>true</traceSsoResponses> to your
an OAuth 2 section in the authentication.xml file.
Warning
Remove <traceSsoResponses>true</traceSsoResponses> from your OAuth 2 configuration
once you have the information you need. Leaving verbose logging enabled can expose potentially
sensitive information in your logs.
Verbose logging lets you check the responses from the OAuth 2 Authorization Server and the data
structure format. The log traces the details received from OAuth2 Authentication Server, including Access-
token, ID-token, JSON responses from fetched Urls (see <namePath fetchUrl="...">), parsed user
profile fields, and parsed User Groups. This information helps you find the source of any misconfiguration
and solve it effectively.
Note
The received access-token and id-token are logged in the raw format received from the provider. To make
them human-readable, they must be decoded using tools like https://jwt.io/.(Choose algorithm RS256.)
Once you've gathered the necessary information, you can move on to Claim scopes for OAuth 2 if you are
configuring an OAuth 2 authorization server or combine multiple lists.
The Oauth2 Authorization Server may not send Group information unless a specific scope is claimed in the
request. The name of the scope to be claimed depends heavily on the implementation and configuration
on the OAuth2 Authorization Server side.
Check that the appropriate <oauth2> section in your authentication.xml, contains list of all the desired
scopes.
Example
The <scope> tag should be within the main <oauth2> tags, not the <groupsSynchronization>
tag.
<scopes>
<scope>openid</scope>
<scope>profile</scope>
<scope>groups_scope</scope>
</scopes>
Once your Group Scopes are defined, you can move on to combine multiple lists (optional) or Querying
the received responses.
A working configuration depends on the SSO provider and how it's configured to send information to
Polarion. Keep in mind that Polarion expects to receive Groups as a flat list of group IDs or names. It
is, however, possible to combine multiple <namePath> attributes to create a final set of Groups to be
synchronized.
Example
The following Group mapping creates a set of Groups by combining memberOf and belongsTo.
<groupsMapping>
<namePath>memberOf</namePath>
<namePath>belongsTo</namePath>
</groupsMapping>
If the memberOf attribute has the IDs group1 and group2 and belongsTo has “group2 and group3;
then the resulting set is merged as group1, group2, group3. (If two Groups have the same ID, they
are considered the same Group within Polarion.
Group names should also be compliant with Polarion's Group naming scheme. (Group names from
the SSO providers are used as Polarion's Group names, but Polarion's Group-IDs for these Groups are
translated into Polarion compliant IDs. (Spaces and special characters are converted to underscores "_".)
Example
An SSO User Group received as System Admini$trator results in:
Caution
Similar User Group names that result in the same ID after going through this process are considered the
same Group by Polarion.
Example
admin_users and admin users are combined into a single Group.
The value defined within a <namePath> element queries the response and extracts the User Group
names supplied by the SSO provider. The extraction process and queries depend upon whether you use
SAML or OAuth2.
Note
The Group Names created in Polarion are identical to the group names sent by the SSO provider. The
Group ID value in Polarion is created as a copy of the Group Name. If an SSO group name contains
characters that Polarion doesn't support, they are replaced with underscores. Unsupported Group ID
characters include:
For SAML, User Groups are supplied by the Identity Provider as part of the SAML assertion XML. The
content of the SAML assertion document is configured on the SAML Identity Provider side. The query
language used for SAML is quite simple; you must specify (in plain text), the name of the XML element
that holds the User Groups.
Example
If the SAML provider sends a SAML Assertion document that contains the following:
<saml2:AttributeStatement>
<saml2:Attribute Name="groups">
<saml2:AttributeValue>group1</saml2:AttributeValue>
<saml2:AttributeValue>group2</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
Tip
For SAML, if you provide no <namePath> element, by default, the mapping tries to query the Group list
from the following element http://schemas.xmlsoap.org/claims/Group.
For OAuth2, User Groups can be provided as part of the received ID-Token or in a separate endpoint that
Polarion must contact using the Access-Token. Because the implementation may differ on the provider end,
the following fallback sequence is used:
1. If the <namePath> element contains the fetchUrl XML attribute, it will contact the specified URL
and use the <namePath> value to parse the Groups from the obtained response.
2. Or it will use the <namePath> value and try to parse the Group Names from the ID-token received
at the beginning of the authorization process.
With OAuth2, you can select the parser you want to use by defining the <responseParser> element
within the authentication.xml file.
• JSONPath (recommended): It is the most versatile and effective parser. It’s capable of parsing
complex JSON responses using path-based queries. (See https://github.com/json-path/JsonPath for
more information.)
(Put <responseParser>jsonpath</responseParser> in your <oauth2> configuration.)
• Attribute Parser (attr): It is a simplified parser that looks for the right JSON element based on the string
provided. It is only recommended for JSON objects with simple structures. The main drawback for this
parser is the potential name ambiguities that can emerge in complex JSON objects.
(Put <responseParser>attr</responseParser> in your <oauth2> configuration.)
Warning
Some previously available parsers were deprecated in Polarion 21R2 and are no longer available.
Example
{
"userId": "[email protected]",
"memberOf": ["group1", "group2"],
"phoneNumbers": [
{
"memberOf" : "work",
"number": "1234567"
},
{
"memberOf" : "home",
"number": "9876543"
}
]
}
• With the attr parser it’s unclear which memberOf should be extracted.
• With the JSONPath parser you can query $.memberOf.* to obtain group1 and group2. Or you can
query $.phoneNumbers[*].memberOf to get groups work and home.
Note
Keep in mind that the parsing result should be a flat list of Groups in the form [“group1”,
“group2”]. Check the following tips and tricks to help you with this.
Example
{ ... "member": [ "/groupAA","/groupBB"], ... }
Then the requested JSON path should return the simple array of values like ["/groupAA", "/
groupBB"]. So the recommended path in this example is $.member.*.
If you used the shorter path $.member, then the parsed piece would be [ ["/groupAA","/
groupBB"] ]. (Note the double brackets.) This might be interpreted as an array containing a single
object (the whole inner brackets), resulting in a single group created with the name ["/groupAA","/
groupBB"].
If the name of the desired field contains a . or another character with reserved meaning for the JSON-
path, like in the following.
Example
{... "https://sso.polarion.com/groups": ["groupA","groupB"], ... }
Then you can encapsulate the field name into square brackets and single quotes in your JSON path like
this:
$.['https://sso.polarion.com/groups'].*
You can select any Group to include or exclude from synchronization with SSO providers. (Even for Groups
originally created via the Group Synchronization process.)
Procedure
4. Click Edit.
If SSO Synchronization Allowed is not selected, further automatic updates are restricted.
This option is available for all Polarion User Groups. (Even new Groups that are created manually.)
What to do next
Caution
If a Group created manually in Polarion has the same ID as a Group synchronized from an SSO provider
(including converted IDs), their contents are merged into the same Group if you don't deselect SSO
Synchronization Allowed.
Note
Read up on the limitations before combining SSO Group synchronizations with manual Group
administration or LDAP Group Synchronization jobs.
• SSO synchronization does not limit the manual administration of Polarion Groups, but we strongly
recommend that you don't make manual Polarion Group changes during peak hours.
• If you have a custom automatic process (like a script that manages User Groups through the
Polarion API or LDAP Group synchronization), don't run them at the same time you run SSO Group
Synchronization.
• Running SSO synchronization while making changes in Polarion's User Administration may also lead to
inconsistencies.
• You should manage User Groups in a single place. (Pick either Polarion or your SSO providers.)
• Logon failures may occur if a significant number of users are trying to log on at the same time because
it might result in many simultaneous attempts for SSO Group Synchronization. (The logon might be
rejected for some users to prevent the Groups from being misconfigured.)
However, these users can safely log on once the Group synchronization is complete.
Tip
Look at the configuration examples before setting up your configuration.
Here are some SSO configuration examples to help you with your authentication configuration.
Example
<oauth2 id="myOauth">
<authorizeUrl>https://myoauth2.example.com/authorize</authorizeUrl>
<tokenUrl>https://myoauth2.example.com/token</tokenUrl>
<clientId>YOUR-CLIENT-ID-HERE</clientId>
<clientSecret>YOUR-CLIENT-SECRET-HERE</clientSecret>
<mapping>
<id>sub</id>
<name fetchUrl="https://myoauth2.example.com/profile”>myName</
name>
<email>myEmail</email>
</mapping>
<scopes>
<scope>openid</scope>
<scope>profile</scope>
<scope>groups_scope</scope>
</scopes>
<traceSsoResponses>true</traceSsoResponses>
<groupsSynchronization>
<enabled>true</enabled>
<groupsMapping>
<namePath>memberOf</namePath>
<namePath fetchUrl="https://myoauth2.example.com/
myorg”>partOf</namePath>
</groupsMapping>
</groupsSynchronization>
</oauth2>
• The name in the user’s profile would be parsed from the field myName in the JSON response received
from the https://myoauth2.example.com/profile URL.
• The email in the user’s profile would be parsed from the myEmail field in the ID-token received from the
https://myoauth2.example.com/token endpoint.
• The list of User Groups woulbe be taken and combined from the following two sources:
◦ A user's Groups would be parsed from the memberOf field in the ID-token received from https://
myoauth2.example.com/token endpoint.
(And the provider includes this info in the token because there was a groups_scope claim in the list
of scopes.)
◦ A user's Groups would also be parsed from the partOf field in the JSON response received from the
https://myoauth2.example.com/myorg URL.
Some OAuth2 authorization servers do not provide the ID-token in the response requested by
<tokenUrl>, so the additional user-info must then be requested with <userUrl>.
Example
<oauth2 id="myOauth">
<authorizeUrl>https://myoauth2.example.com/authorize</authorizeUrl>
<tokenUrl>https://myoauth2.example.com/token</tokenUrl>
<userUrl>https://myoauth2.example.com/userinfo</userUrl>
<clientId>YOUR-CLIENT-ID-HERE</clientId>
<clientSecret>YOUR-CLIENT-SECRET-HERE</clientSecret>
<mapping>
<id>sub</id>
<name>myName</name>
<email>myEmail</email>
</mapping>
<scopes>
<scope>openid</scope>
<scope>profile</scope>
<scope>groups_scope</scope>
</scopes>
<groupsSynchronization>
<enabled>true</enabled>
<groupsMapping>
<namePath>memberOf</namePath>
</groupsMapping>
</groupsSynchronization>
</oauth2>
• This OAuth2 authorization server does not provide an ID-token on the https://
myoauth2.example.com/token
• The user’s name and email would be parsed from the myName and myEmail fields in the JSON
response received from https://myoauth2.example.com/userinfo.
• The user's Group list would be parsed from the memberOf field that's also in the JSON response
received from https://myoauth2.example.com/userinfo,
Example
<oauth2 id="myOauth">
<authorizeUrl>https://myoauth2.example.com/authorize</authorizeUrl>
<tokenUrl>https://myoauth2.example.com/token</tokenUrl>
<clientId>YOUR-CLIENT-ID-HERE</clientId>
<clientSecret>YOUR-CLIENT-SECRET-HERE</clientSecret>
<responseParser>jsonpath</responseParser>
<mapping>
<id>sub</id>
<name>$.myName</name>
</mapping>
<scopes>
<scope>openid</scope>
<scope>profile</scope>
<scope>groups_scope</scope>
</scopes>
<groupsSynchronization>
<enabled>true</enabled>
<groupsMapping>
<namePath>$.memberOf.*</namePath>
</groupsMapping>
</groupsSynchronization>
</oauth2>
• The user’s name would be parsed from the ID-token received from the https://
myoauth2.example.com/token endpoint at JsonPath $.myName.
• The user's Group list would be parsed from the ID-token received from the https://
myoauth2.example.com/token endpoint at JsonPath $.memberOf.
Tip
Explore these useful links that can provide you with the necessary tools to aid in your configuration and
understand potential misconfiguration issues.
Useful links
Here's a list of external links to third-party tools that will help you configure your SSO User Groups with
Polarion:
You can synchronize User Groups with LDAP for a single LDAP server.
Synchronizing User Groups with LDAP is a little different than synchronizing users with LDAP.
Procedure
1. Even though your configuration can contain multiple <ldap> sections that connect your Polarion
with multiple LDAP servers, you can only select a single LDAP server to synchronize User Groups. The
target LDAP configuration should contain the following tag:
<ldap … syncUserGroups=”true”>
2. The target LDAP configuration must also be one of those with synchronization enabled by a
<synchronization> section.
Tip
See LDAP tips and tricks for more information.
4. Only users that satisfy all of the following criteria can be added to a Group.
• Only existing Polarion users can be added to the Group.
For new users, you can combine the User Group Update with Create New Users option.
• Only a user matching the group’s LDAP Search Filter can be added in that Group.
If a user no longer matches the filter, they are removed from the Group.
• Only users involved in the LDAP user synchronization are taken in consideration.
(All users that don't match the selected LDAP configuration are excluded from the Group.)
Procedure
1. Log on with administrator permissions for the repository. If you have a clustered server environment,
you need these permissions for the repository of any server instance you want to configure for LDAP
synchronization.
Note
If the selected LDAP configuration has Group synchronization disabled, the option remains inactive
and can’t be selected.
6. Click Synchronize
The synchronization process begins and an informative message appears.
7. When complete, the final message and a detailed report appears.
You can synchronize users in Polarion for a specific set of User Groups by setting up and running the
following job in Polarion's Scheduler.
polarion.jobs.ldap.userGroups.synchronization
It synchronizes each User Group with the Search Filter that was entered on the Group's page in
Administration.
Example
The job appears in the Monitor under the name Update all User Groups.
It synchronizes users in Polarion. If it finds new users, they are created. If existing users are out of sync,
they will not be updated. All User Groups are checked and the necessary users assigned to them.
Example
The job appears in the Monitor under the name Update some User Groups.
It tries to synchronize the Polarion users from the dev-user-group and qa-users Groups defined in the job.
If it finds new users, they are created. If existing users are out of sync, they are updated. Only the defined
User Groups are synchronized. All other User Groups and their LDAP queries are ignored.
Tip
To run scheduled jobs at any time, go to the Monitor topic in Navigation, select the job and click
Execute Now.
Some characters can break the syntax of your authentication.xml file configuration and must be escaped.
To adhere to XML specifications, the characters below are reserved exclusively for XML syntax.
If you want to use them in tags within the authentication.xml file, you must escape them with the
following alternatives:
(You must also escape other characters that are not in the encoding that serializes the document.)
Examples
<searchFilter>(&(field1=boo)(field2=boo))</searchFilter> (Incorrect)
<searchFilter>(&(field1=boo)(field2=boo))</searchFilter> (Correct)
You can also use <![CDATA[...]]> tags to avoid escaping XML reserved characters one at a time.
<searchFilter><![CDATA[(&(field1=boo)(field2=boo))]]></searchFilter>
Web services can authenticate by the password method, Access Tokens, or by LDAP if the authentication
configuration allows it.
Web services support password authentication and token authentication for Teamcenter Security Services.
Token authentication for Teamcenter Security Services is available only if Polarion is configured to
use Teamcenter SSO with the legacy properties. (See Polarion SDK documentation: Web services doc:
SecurityWebService interface: SessionWebService.logInWithToken) .
The main way to authenticate for web services is the password authentication method, which is
available even if Polarion is configured to use SSO only. (See SessionWebService.logIn in the SDK
documentation.)
LDAP authentication is controlled by the attribute <allowWebServices>. There are two possible cases:
1. The configuration in authentication.xml contains the password authentication method. (See topics
for Password for new or updated installation.)
The configuration may not contain the <ldap> element, or may contain it without the
<allowWebServices> attribute.
Polarion will try to authenticate against the passwd_credentials file and <ldap> elements which
contain <allowWebServices=true>, in order of occurrence (like the regular user authentication
flow with password).
2. The configuration in authentication.xml does not contain the password authentication method.
In this case, the configuration should contain at least one <ldap> element with
<allowWebServices=true>.
Polarion will try to authenticate against <ldap> elements which contain
<allowWebServices=true>, in order of occurrence. If it finds no such elements, a web service
exception is thrown.
Note
The LDAP configuration is per provider. More than one provider can be included, one per <ldap>
element.
Authentication settings can be complex, and a misconfiguration could lead to you and your users being
unable to log on to Polarion. This section offers some tips on avoiding a lockout and recovering from one if
it happens.
No matter what authentication method or combination of methods you intend to use, create a local user
account with administrative permissions.
Even if you don't want to support the <password> authentication method for your users, you can
temporarily allow it, access the system with a local admin account, and sort out your misconfiguration.
Procedure
Note
• Before adopting the authentication.xml, it is the default authentication method, unless you
configured otherwise in the polarion.properties file.
• Make sure that your authentication.xml contains a <password> configuration.
e. Setup the necessary administration roles and permissions for this user.
3. Setup a new authentication configuration that suits your needs.
The user you configured can now use any other authentication method.
If you do not use <password> authentication, the user can't use their password to log on, but the
record of their password remains in the system and can be used at any time in the future.
Note
As of Polarion 21 R1, a user's local password does not break if they log on with another available
authentication method.
Procedure
1. Re-enable authentication by local password and disable all the other authentication methods.
• For Kerberos you do it in the polarion.properties file.
• If you use the authentication.xml method, access the file directly on the file system level. Edit the
content, make sure it contains a<password> section, comment out all the other sections, save the
file and Restart the Polarion service.
• On cluster setup you need to restart Polarion service on coordinator and all nodes or instances.
2. Now you should be able to log on to Polarion with the user you created above via its local password
and fix your broken configuration.
Tip
Create the new authentication.xml from inside of Polarion via the built-in editor.
If you decide to do it outside of Polarion, you could run into the following problems:
If any of the above occurs, you may decide to remove the created authentication.xml file and recreate a
configuration from scratch.
Procedure
Note
You can start the service in normal mode. (A reindex is not required on a standalone installation.)
4. You can now log on to Polarion with the administrative account via the local password and create the
authentication.xml correctly using the built-in editor.
Procedure
Note
A reindex is required in a clustered environment, or the corrupted XML will persist and get
redistributed to nodes.
4. You can now log on to Polarion with the administrative account via the local password and create the
authentication.xml correctly using the built-in editor.
If you update the bind password or change SAML certificates, you must reload the authentication.xml file.
Reloading the authentication.xml file using the following method is intended for system administrators
that do not have access to Polarion but would like to modify the authentication.xml file.
Note
This reload feature should not be used to create or remove the initial authentication.xml file. It should
only be used to refresh the configuration on the fly without restarting the Polarion service. (After editing
the existing authentication.xml file on the file-system level.)
Procedure
1. Add the following property to the Configuration Properties section on the global level (
Administration Configuration Properties) and set it to true:
authentication.xmlReload.enabled
(If false, the call will be rejected.)
2. Edit the authentication.xml file and save your changes.
3. Do one of the following:
a. Open the <polarion_server>/polarion/authentication-reload URL in your browser.
(Where <polarion_server> is the domain of your Polarion server.)
Note
For cluster installations, .../authentication-reload can be called from the cluster's (or any
node) URL.
SAML metadata is an XML document containing the information required to interact with SAML-enabled
identity or service providers.
It includes:
Typically one metadata document is generated for your service provider and sent to all the identity
providers you want to enable single sign-on with.
Each identity provider then makes its metadata available for import into your service provider application.
To access the metadata of your configured authenticator, you might use the following URI on your existing
installation: /polarion/saml2/sp/metadata/
If you only have one SAML provider configured, then the metadata appears immediately. If you have
multiple providers configured, you can specify a target ID in the same URI as follows: /polarion/
saml2/sp/metadata/<provider_id>
Tip
Make sure you can access the SAML provider, and its ID is correct first.
For SAML SSO and TeamCenter SSO, the logging process is redirected to the IdP or the Team Center
Log-on. Since embedding the log-on page in the internal log-on popup IFrame may be a security issue, TC
and SAML SSO have internal log-on in IFrame disabled by default. This means that the popup will prompt
you to log on in a new tab that closes, and you can continue working in the original tab.
If you want to enable the log-on form in the internal log-on popup, you can set this property in the
polarion.properties file:
com.siemens.polarion.security.disableIFrameLogin=false
Note
Before setting this property, make sure you IdP support the log-on form in an IFrame. For example, ADFS
does not support this, and so it will be not possible to log in via internal popup if the IFrame is disabled.
Common
All the authentication providers except password use some common parameters. This topic provides a
more in-depth understanding of the attributes and elements found in the examples in the configuration
topics.
Attributes
Parameters
Auto-create Enable or disable the automatic creation of Polarion accounts for new users
logging on for the first time.
Global role assignment Specify the global role(s) assigned to new accounts created by Auto-create.
Provider identification Provide a human-readable name for your configured authentication providers,
to appear in user profiles and the log-on screen.
Pre-21 R1
Element Occurrence Position Default Description equivalent
<autocre Optional, max child of See <enabled> Controls whether Settings in the
ate> = 1 time <ldap>, a new account is Administration page
<saml> , created in Polarion User Management >
<oauth2 for users who log Auto-create
> or on for the first
<tcss> time via the provider The <autocreate>
specified in the section is now
parent element. applicable per
provider, while the
versions prior 21 R1
had only one global
setting.
<enable Required, child of Defaults to Enables or disables (As above)
d> Boolean <autocre false if the auto-create
ate> <autocreate> feature.
element is
omitted in the
provider
configuration.
<globalR Optional child of List of global roles to System property
oles> <autocre be assigned to new rolesForNewUserAc
ate> auto-created users. count
Pre-21 R1
Element Occurrence Position Default Description equivalent
Caution
If no <role>
is specified, new
users cannot log
on.
LDAP
This topic contains technical reference information specific to user authentication with LDAP. It provides
a more in-depth understanding of the attributes and elements in the examples in the LDAP configuration
topics.
Note
LDAP mapping differs from other SSO methods (OAuth 2, SAML) in that mapping is ordered, and the
following tags in the <mapping> section must be in the order listed below, or they won't work.
1. <id> (required)
2. <name> (none, one, or multiple)
3. <email> (none, one, or multiple)
4. <description> (none, one, or multiple)
LDAP-specific parameters
<url> The LDAP host server URL. Including the port number. Typically on
the ldap protocol.
• Occurrence: required
• Position: child of <LDAP>
• Administration settings or Apache configuration.
<bindDn> The identity used to search for users
• Occurrence: required
• Position: child of <LDAP>
• Pre-21R1 equivalent: Administration settings or Apache
configuration.
<bindPassword> or The bind password. The password can be stored as plain text.
<bindPassword
userAccountVaultKey="vaultKey" / For example:<bindPassword>booValue</bindPassword>
>
The secret password can be safely saved in the User Account Vault
and referenced.
Entering both the value and the key in the property does not break
the syntax validation. However, only the vault key is used. In the
example, only the fooKey is taken.
<bindPassword userAccountVaultKey="fooKey"
>booValue</bindPassword>
• Occurrence: required
• Position: child of <LDAP>
• Pre-21R1 equivalent: System property ldap.bind.password
<baseDn> The base distinguished name (distinguishedName attribute) of
the LDAP node to begin searching for users in.
For example:
CN=Users,DC=company,DC=co
Tip
When entering a distinguishedName (DN), use upper case
node descriptors.
For example:
• Occurrence: required
• Position: child of <LDAP>
• Pre-21R1 equivalent: Administration settings or Apache
configuration.
<mapping> Defines how the information obtained from the LDAP provider is
mapped into the user's profile.
Unlike the rest of the XML, you must order the tags under this
section in the following specific sequence:
1. <id>
(required)
2. <name>
(none, one or multiple)
3. <email>
(none, one or multiple)
4. <description>
(none, one or multiple)
• Occurrence: required
• Position: child of <LDAP>
• Default: none - see child elements.
• Pre-21R1 equivalent: Settings in Administration section in
Polarion's GUI for synchronization of the user base with the LDAP
server. Apache configuration for LDAP.
<id> The LDAP attribute to use as the user ID for Polarion users.
Frequently used values include:
Note
In contrast to other tags in the mapping section, the value in this
field is not quoted by the % character.
You can compose the full name by chaining strings and values from
various LDAP fields.
Multiple occurrences of the tag are possible, and the first applicable
mapping is always used. A mapping is applied if the mapping string
field attributes are present and populated in the LDAP user node
attribute(s).
You can compose the email address by chaining strings and values
from various LDAP fields.
Multiple occurrences of the tag are possible, and the first applicable
mapping is always used. A mapping is applied if the mapping string
field attributes are present and populated in the LDAP user node
attribute(s).
Multiple occurrences of the tag are possible, and the first applicable
mapping is always used. A mapping is applied if the mapping string
field attributes are present and populated in the LDAP user node
attribute(s).
<searchFilter> A filter expression that refines found user results. It can be any valid
LDAP query.
For hints on how to compose complex LDAP queries see the LDAP
tips and tricks section.
Caution
If you use XML reserved characters in your values, but you must
escape them.
• Occurrence: optional
• Position: child of <LDAP>
• Pre-21R1 equivalent: Administration settings or Apache
configuration.
<searchSubtree> Set to true to search through the specified LDAP node and all the
sub-nodes below it.
Set to false to limit the search to users directly under the specified
LDAP node. No sub-nodes below it will be considered.
Tip
See the Scope of the LDAP Search section for more information.
CN=Polarion Users,DC=company,DC=com.
See the User search options section in LDAP tips and tricks for
more information.
If this field is not empty, please make sure that it, and the Base DN
field, does not contain spaces around node-separating commas.
For example:
If this field is not empty, please make sure that the Group Member
Attribute is also filled in.
• Occurrence: optional
• Position: child of <LDAP>
• Default:
• Pre-21R1 equivalent: Administration settings or Apache
configuration.
<groupMemberAttriute> A multi-valued attribute of a Group DN node that contains the
members of that group (often a member from the groupOfNames
object class).
• Occurrence: optional
Caution
If disabled, it also blocks the ability to import all the user details
via auto-create.
Note
A user's profile is not updated when they log on via LDAP,
regardless of this setting.
• Occurrence: optional
• Position: child of <LDAP>
• Default: none - see child elements
• Pre-21R1 equivalent: settings in Administration for "Synchronize
with LDAP"
<enabled> Enable (true) or disable (false) synchronization with LDAP
Caution
If no <role> is specified, new users cannot log on.
• Occurrence: optional
• Position: child of <synchronization>
• Default: null
• Pre-21R1 equivalent: System property rolesForNewUserAccount
<role> The name of the global role to be assigned to new accounts.
• Occurrence: Optional
• Position: child of <LDAP>
• Default: null - unspecified
• Apache configuration.
<followReferralsLimit> The integer parameter. It limits the depth of nested referrals.
• Occurrence: Optional
• Position: child of <LDAP>
• Default: null - unspecified
• Apache configuration.
• Occurrence: Optional
• Position: child of <LDAP>
• Default: null - unspecified
• Apache configuration.
OAuth 2
This topic contains technical reference information specific to user authentication with OAuth 2. It
provides a more in-depth understanding of the attributes and elements in the examples in the OAuth
2 configuration topics.
Note
Mapping for OAuth 2 is not ordered, and tags cannot repeat. (This differs from LDAP mapping).
OAuth-specific attributes
OAuth-specific parameters
Occurrence &
:
Element Position Description
<mapping> Optional Defines how the information obtained from the OAuth2
provider is mapped into the user's profile. If the userUrl
parameter is specified, the response from this endpoint
Default child of <oauth2> will be used to parse. Otherwise Polarion will try to use
id_token received from the tokenUrl endpoint.
If not specified, then the profile is mapped by the
default values of child elements. Pre-21 R1 equivalent
<name fetchUrl="url"> child of <mapping> Some identity providers do not provide some data in
the user profile or id_token, so it's necessary to request
it from a separate endpoint, specified by a fetchUrl
Default: attribute. The mapping will be applied to the response
from this endpoint. If empty, or an absent value is parsed,
name user profile will get parsed email value
<entitlements> Optional The parent tag for the <userClaim> tag below.
N/A
<userClaim> child of <entitlements> • Use this tag inside the <entitlements> tag above if
you have users that can authenticate via a connected
IdP, but you only want some of them to be able to use
Polarion or be assigned a license.
Occurrence &
:
Element Position Description
Note
The <userClaim> is verified <before> a new user
gets created, so erroneous user accounts are not
added to your repository.
Example:
<oauth2
id="oauth_simple_sample">
<authorizeUrl>https://
oauthprovider.example.com/
authorize</authorizeUrl>
<tokenUrl>https://
oauthprovider.example.com/
oauth/token</tokenUrl>
<clientId>[Your_client_id_he
re]</clientId>
<clientSecret>[Your_secret_h
ere]</clientSecret>
<entitlements>
<userClaim>
<key>$.entitlements.userType
</key>
<value>polarion_user</value>
</userClaim>
</entitlements>
</oauth2>
{
"iss": "http://my-
domain.auth0.com",
Occurrence &
:
Element Position Description
"sub": "auth0|123456",
"aud": "my_client_id",
"exp": 1311281970,
"iat": 1311280970,
"name": "Jane Doe",
"given_name": "Jane",
"family_name": "Doe",
"entitlements": {
"userType":
["polarion_user"]
},
"tenantId": "uuid4
string",
"birthdate": "0000-10-31",
"email":
"[email protected]",
"pict
}
Pre-21 R1 equivalent
N/A
<email fetchUrl="url"> child of <mapping> Some identity providers do not provide some data in user
profile or id_token, so it's necessary to request it from
a separate endpoint, specified by a fetchUrl attribute.
Default The mapping will be applied to the response from this
endpoint. If empty, or an absent value is parsed, user
email profile will get empty email field
<description fetchUrl="url"> child of <mapping> Some identity providers do not provide some data in user
profile or id_token, so it's necessary to request it from a
separate endpoint, specified by a fetchUrl. The mapping
Default will be applied to the response from this endpoint. If
empty, or an absent value is parsed, user profile will get
null empty description field
Occurrence &
:
Element Position Description
com.siemens.polarion.security.oauth2.userMapping.d
escription
System Property:
com.siemens.polarion.security.oauth2.authorizeUrl
<tokenUrl> Required The URL of the endpoint from which an access token is
requested.
child of <oauth2>
Pre-21 R1 equivalent
System Property:
com.siemens.polarion.security.oauth2.tokenUrl
System Property:
com.siemens.polarion.security.oauth2.clientId
<clientSecret userAccountVaultKey="vaultKey" /> child of <oauth2> The key in the User Account Vault, for the secretly saved
value.
<clientSecret userAccountVaultKey="fooKey"
>booValue</clientSecret>
Pre-21 R1 equivalent
System Property:
com.siemens.polarion.security.oauth2.clientSecret
Occurrence &
:
Element Position Description
Pre-21 R1 equivalent
System Property:
com.siemens.polarion.security.oauth2.tokenUrlMetho
d
<userUrl> Optional The URL of the provider endpoint that issues an ID token
as part of the process of issuing an Access token. Not
all providers do this. Check developer documentation of
Default: child of <oauth2> the provider you are configuring to see if they use this
approach. If not needed, leave the default null value.
null
Pre-21 R1 equivalent
System Property:
com.siemens.polarion.security.oauth2.userUrl
System Property:
com.siemens.polarion.security.oauth2.scope
<scope> Required if <scopes> is present Specifies the scope of the permissions the Authorization
request is asking for. Value is string type. The value itself
should be a scope/permission identifier recognized by the
Default: child of <scopes> identity provider you are configuring. For example, on the
Microsoft identity platform's Microsoft Graph resource,
openid Mail. Send in the request asks only to grant permission
to send an email and nothing else beyond that scope. The
value set in this parameter is passed as a URL parameter
profile email to the request. Consult the provider's documentation for
valid values.
Caution
We do not recommend including secret scopes in the
Access Token sent back to Polarion from IdP.
If you must do so, you should list any token claim that
should remain hidden from end users in the following
Configuration property:
authentication.oauthToken.uiBlockedClaims
Pre-21 R1 equivalent
See <scopes>
Occurrence &
:
Element Position Description
attr
Pre-21 R1 equivalent
N/A
<replaceForbiddenCharacters> Optional, Boolean If false, then user names with forbidden characters in
IdP responses are rejected during Auto-create. If true,
then Polarion replaces forbidden characters in a user
Default: child of <oauth2> name when a user name from an identity provider (IdP)
response contains them.
false
Warning
Allowing automatic replacement of forbidden
characters can lead to a security vulnerability where
two IdP user names are mapped to the same user
name on the Polarion side. Administrators need to
ensure that replacement is safe from a security
standpoint for all possible users, and automatic
replacement is not ambiguous when mapping them.
For example:
Pre-21 R1 equivalent
System Property:
com.siemens.polarion.security.auth.replaceForbidden
Characters.enabled
Position
<tokenExchangeParameters> Optional It is the parent tag for a list of services that can be used for
Token Exchange flow.
Child of <oauth2>
Occurrence &
:
Element Position Description
<tokenExchangeParametersSetting> Required for: It configures a Token Exchange Flow with a given service.
The "usedFor" attribute defines the ID for the configuration
.
<tokenExchangeParameters>
Child of
<tokenExchangeParameters>
<tokenUrl> Required for: It works like the <tokenUrl> child of <oauth2>, but instead
refers to the endpoint used for Token Exchange.
<tokenExchangeParametersSetting
>
Child of
<tokenExchangeParametersSetting
>
<clientId> Required <clientId> and <clientSecret> are similar to the ones from
<oauth2>, but this refers to the endpoint used for Token
Exchange.
<clientSecret>
<parameter> Optional This represents the list of key-value pairs that the server
may require to properly request a new exchange token.
Examples:
Example:
<tokenExchangeParameters>
<tokenExchangeParametersSetting usedFor="TcAuthentication">
<tokenUrl>samauth.myserver.com/token</tokenUrl>
<clientId>myClientId</clientId>
<clientSecret>myClientSecret</clientSecret>
<parameter name="Key 1">[Value 1]</parameter>
<parameter name="scope">openid sam_account profile</parameter>
</tokenExchangeParametersSetting>
</tokenExchangeParameters>
Position
<traceSsoResponses> Optional, Boolean If true, the verbose information for the logon and
Group synchronization process is written in the logs. Can
help diagnose and fix potential misconfiguration issues.
Default: child of <oauth2> Don’t forget to turn this off, when you complete the
configuration.
Occurrence &
:
Element Position Description
false
Child of <groupsSynchronization>
false
<namePath> Required if <groupsMapping> is The name or path to the field that contains the list of
present. Groups that a user is a member of. Multiple attributes,
each containing a different list of Groups, are supported.
<namePath fetchUrl=”url”>
Multiple instances allowed.
The value can be the name of the field or JSON path,
based on the parser in use (See <responseParser>).
Child of <groupsMapping>
Warning
We recommend that you only use numbers and US-
Latin characters in Group Names and avoid any non-
US-Latin characters like diacritics, Japanese/Chinese
characters, and emoticons.
Position
<usedFor> Required for Teamcenter Share The <usedFor> tag can be defined as follows:
but optional for other OAuth 2
configurations.
• An OAuth 2 configuration without the <usedFor> tag
is only used for Polarion login authentication.
Child of <oauth2>
Occurrence &
:
Element Position Description
<nonce> Required for Teamcenter Share When used, it enables the ability to use a nonce in
but optional for other OAuth 2 the auth URL. A nonce is a unique and random string
configurations. generated by the client that allows the server to verify
that a request has never been made before.
Child of <oauth2>
<accessKeyInfoUrl> Required for Teamcenter Share The URL that retrieves access key information
Child of <oauth2>
<introspectionUrl> Required for Teamcenter Share The URL used to decrypt sensitive User Claims
Child of <oauth2>
<xceleratorScopes> Required for Teamcenter Share A predefined list of scopes that are used for Teamcenter
Share.
Child of <oauth2>
SAML
This topic contains technical reference information specific to user authentication with SAML. It provides
a more in-depth understanding of the attributes and elements found in the configuration examples in the
SAML configuration topics.
Note
Mapping for SAML is not ordered, and tags cannot repeat. (This differs from LDAP mapping).
SAML-specific attributes
SAML-specific parameters
<mapping>
• Occurrence: optional
• Position: child of <saml>
• Default: If not specified, than the profile fill be mapped by all the default values of child elements.
• Pre-21R1 equivalent: N/A
Defines how the Assertion response from the SAML provider is mapped into the user's profile.
Note
There's an additional <mapping> attribute below exclusively for the synchronization of User Groups.
<id>
• Occurrence: optional
• Position: child of <mapping>
• Default: Matches the NameID provided in SAML response
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.userMapping.alternativeId
User's ID. Unique across Polarion. If the value is empty, or mapping does not match, it falls back to
NameId from the SAML response. If the custom mapping is not configured, or not matching anything,
the default is used so the user's profile on the Polarion side always has some ID.
<name>
• Occurrence: optional
• Position: child of <mapping>
• Default: Matches namespace "http://schemas.xmlsoap.org /ws/2005/05/identity/ claims/name".
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.userMapping.name
User's full name. If the value is empty or mapping does not match, the user's ID is copied into user's
name.
<email>
• Occurrence: optional
• Position: child of <mapping>
• Default: Matches namespace "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.userMapping.email
The name of the SAML attribute used to fill Description in user's Polarion account.
<identityProviderMetadataUrl>
• Occurrence: optional
• Position: child of <saml>
• Default: null
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.identityProviderMetadataUrl
Identity Provider metadata location where Polarion will read log on/log off endpoints and certificate, and
other information to configure the application for SAML authentication. The location can be on a remote
server on HTTPS protocol or a local file.
<sloServiceUrl>
• Occurrence: optional
• Position: child of <saml>
• Default: null
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.sloServiceUrl
The URL to the Identity Provider's (IdP) Single Logout service. The logout response will be posted to
this URL as the SAMLRequest parameter. The configuration of Single Logout Service is optional and then
nullable.
<ssoServiceUrl>
• Occurrence: optional
• Position: child of <saml>
• Default: null
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.identityProviderMetadataUrl
The URL to the Identity Provider's (IdP) AuthnRequest service. The AuthnRequest will be posted to this
URL as a SAMLRequest parameter.
<certificatePath>
• Occurrence: optional
• Position: child of <saml>
• Default: null
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.certificatePath
The path where Polarion will search for a certificate for SAML response validation. Polarion will search
the specified directory for *.crt or *.cer files. The first certificate found is used for SAML authentication.
<forceAuthn>
• Occurrence: optional, Boolean
• Position: child of <saml>
• Default: false
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.forceAuthn
Controls whether or not the Identity Provider will force the user to re-authenticate even if user still has a
valid session.
<issuer>
• Occurrence: optional
• Position: child of <saml>
• Default:
Base URL of identityProvider
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.issuer
The URL of the Identity Provider (IdP) that will issue the SAML 2.0 security token with user authentication
info.
<assertionConsumerServiceUrl>
• Occurrence: optional
• Position: child of <Saml>
• Default: <base.url>/polarion/
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.assertionConsumerServiceUrl
Caution
IdP URLs in SAML SSO must contain a trailing slash character (/). Example: https://
polarion.ourserver.com/polarion/
<relyingPartyIdentifier>
• Occurrence: optional
• Position: child of <saml>
• Default: See description, below.
• Pre-21R1 equivalent: com.siemens.polarion.security.saml.relyingPartyIdentifier
The entity identification or the issuer for SAML AuthnRequest. The default value is <base.url>
without a trailing slash character (/) at the end.
<replaceForbiddenCharacters>
• Occurrence: optional, Boolean
• Position: child of <saml>
• Default: false
• Pre-21R1 equivalent: com.siemens.polarion.security.auth.replaceForbiddenCharacters.enabled
If false, then user names with forbidden characters in IdP responses are rejected during Auto-create. If
true, then Polarion replaces forbidden characters in a user name when a user name from an identity
provider (IdP) response contains them.
Warning
Allowing automatic replacement of forbidden characters can lead to a security vulnerability where
two IdP user names are mapped to the same user name on the Polarion side. Administrators need
to ensure that replacement is safe from a security standpoint for all possible users, and automatic
replacement is not ambiguous when mapping them.
For example:
The ampersand (@) and dash (-) characters at the beginning of a user name are also replaced by
underscore ( _ ). For example:@user1 maps to _user1
<groupsSynchronization>
• optional
• child of <saml>
• Controls how the User Groups sent by a SAML provider are synchronized in Polarion.
• Pre-21R1 equivalent: N/A
<enabled>
• Required if <groupsSynchronization> is present
child of <groupsSynchronization>
• Enables or disables the synchronizing of user Groups with a SAML provider.
• Default: false
• Pre-21R1 equivalent: N/A
<groupsMapping>
• optional
• child of <groupsSynchronization>
• The list of the SAML Assertion attributes sent by a SAML provider, that list the user Groups.
If not specified, it will attempt to get the Groups from the assertion attribute name "http://
schemas.xmlsoap.org/claims/Group"
• Pre-21R1 equivalent: N/A
<namePath> / <namePath fetchUrl=”url”>
• Required if <groupsMapping> is present.
Multiple instances allowed.
• Child of <groupsMapping>
The name of the attribute in the SAML assertion sent by a SAML provider. The attribute should contain a
list of Groups that a user is a member of. Multiple attributes, each containing a different list of Groups
are supported.
Group Names created in Polarion are identical to the group names sent by the SAML provider. If a SAML
group name contains characters that Polarion doesn't support, they are replaced with underscores.
Warning
We recommend that you only use numbers and US-Latin characters in Group Names and avoid any
non-US-Latin characters like diacritics, Japanese/Chinese characters, and emoticons.
Tip
Pre-21 R1 equivalent refers to system configuration properties unless otherwise noted.
This topic contains technical reference information specific to user authentication with Teamcenter
Security Services. It provides a more in-depth understanding of the attributes and elements in the
examples provided in the Teamcenter Security Services configuration topics.
Occurre Posit
Element nce ion Default Description Pre-21 R1 equivalent
loginUrl Required Child The URL to the System property:
of Identity
<tcss Provider's (IdP) com.siemens.polarion.security.tc
> login page. sso.loginUrl
serviceUrl Required Child The URL to the System property:
of Identity
<tcss Provider's (IdP) com.siemens.polarion.security.tc
> service. sso.serviceUrl
paramAppU Optional Child APP_USER The redirect System property:
serId of _ID request
<tcss parameter com.siemens.polarion.security.tc
> name to sso.paramAppUserId
extract user
name.
paramSessi Optional Child SESSION_K The redirect System property:
onKey of EY request
<tcss parameter com.siemens.polarion.security.tc
> name to sso.paramSessionKey
extract session
key.
Password
This topic contains technical reference information specific to user authentication with passwords.
It is intended for those who want a more in-depth understanding of the attributes and elements found in
the examples provided in the password new installation and update topics.
Attributes
Parameters
Self-registration Enables new users to register for an account from the Polarion log-on screen.
Global role assignment Specify the global role(s) assigned to new accounts created by user self-
registration.
Pre-21 R1
Element Occurrence Position Default Description equivalent
<registration Optional child of User self- Controls whether or System
> <password> registratio not the Create your property
n is Polarion Account enableCreate
disabled link appears on the AccountForm
log-on screen.
<enabled> Required id child of false If true the self- (See above)
<registration> <registration registration link
is present. > appears. If false, it
is hidden.
<globalRoles Optional child of List of global roles System
> <registration to be assigned to property
> new self-registered rolesForNewU
users. serAccount
Pre-21 R1
Element Occurrence Position Default Description equivalent
Caution
If no <role> is
specified, new
users cannot log
on.
Miscellaneous
This topic contains reference information for user authentication that is not specific to any authentication
method and is universally applicable to all methods.
Note
If you create the authentication.xml file from the built-in editor in Polarion or populate the default
template, the XML header contains an automatically prefilled link to the XSD (XML Schema Definition)
located on your Polarion server.
Warning
Using Basic Authentication is deprecated and will be removed in future releases. Use Personal Access
Tokens instead.
To enable certain integration use cases, Basic Authentication is enabled by default for some OSLC
resource URLs, but only if Password Authentication is enabled.
To disable Basic Authentication for OSLC, please use the following in the authentication.xml file:
Note
If password authentication is disabled, Basic Authentication is also disabled by default.
Eleme Defau
nt Occurrence lt Description
allow Required, Defines if Basic Authentication is allowed for OSLC HTTP endpoints that
Oslc Boolean contain /polarion/oslc/services in their URL.
6. Reference
Administration reference
This topic contains reference information about the default Polarion folder structure after installation.
Where there are differences between Windows and Linux, 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 process.
Windows structure
In documentation, [POLARION_HOME] means the root folder of the installation. For Windows systems, it
refers to the default path used by the Windows installer: C:\Polarion.
After installation on a Windows system, the Polarion folder ([POLARION_HOME]) contains the following
subfolders which are unique to the Windows installation - that is, they are not created for Linux
installations:
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. However, it is no longer bundled due to
licensing issues. It is necessary to obtain and install the Java version recommended in
the Polarion Deployment and Maintenance Guide. It's available in the Polarion section of
Support Center.
polarion *.lnk-files (desktop shortcuts) for starting and stopping the Polarion server and Apache
shortcuts services.
Linux structure
For Linux systems, [POLARION_HOME] refers to the location where the installation script 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
(that is, not present in a Windows installation).
Common folders
This section covers folders that are common to both Windows and Linux installations.
This folder contains all data that Polarion operates with. By default the following folders 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 license (in cases where you have multiple license types or licenses).
• 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 — users defined in the passwd_credentials file — cannot have passwords
containing characters not available in the US-ASCII character set.
1. However, if Polarion server is running on Linux, LDAP users can have non-ACSII passwords, provided
the following line exists uncommented in the polarion.properties system configuration properties
file: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 the second example should be replaced with a local Windows encoding such as 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.
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 Windows, or httpd on Linux) also runs. It
usually runs two processes with the same program name (httpd.exe on Windows, or httpd on Linux).
postgres, svnserve (if configured), colleno and node.js are also running.
In rare cases, it might happen that the colleno or node.js process is not shut down when shutting down
Polarion. If that happens, we recommend that you stop those processes manually.
Note
You can view the default paths for Polarion components in the Polarion folder structure topic.
In addition to the extensive configuration and customization options available in the Polarion
Administration interface, there is a set of system-level configuration properties available to administrators
and developers that affect how various Polarion system processes and functions work or behave.
The system configuration 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:
You can edit the system properties file using a text editor application such as Notepad or Vi. There is no
user interface for it in the Polarion portal.
Note
• 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.
There is a set of advanced system-level properties that can be set and modified in the Configuration
Properties topic of Administration. These can be edited online, and changes do not require restart of the
server to take effect.
Reference documentation
All currently active configuration properties are documented in the Polarion System Configuration
Properties Reference, a PDF document available on the Documentation page of the Polarion product
center on Support Center. An updated version of the documentation is published with every Polarion
release.
Polarionuses cron - a time-based job scheduling utility that lets administrators schedule jobs to run
periodically at specified times, dates, or intervals.
This topic provides basic information and usage examples that may be helpful when configuring
scheduled jobs.
Job scheduling
The following table contains examples of cron expressions used in job scheduling.
Expression Meaning
0 0 12 * * ? Fire at 12pm (noon) every day.
0 15 10 ? * * Fire at 10:15 am every day.
0 15 10 * * ? Fire at 10:15am every day.
0 15 10 * * ? * Fire at 10:15am every day.
0 15 10 * * ? 2006 Fire at 10:15am every day during the year 2006.
0 * 14 * * ? Fire every minute starting at 2 pm (14:00) and ending at 2:59 pm
(14:49), every day.
0 0/5 14 * * ? Fire every 5 minutes starting at 2 pm (14:00) and ending at 2:55 pm
(14:55), every day.
0 0/5 14,18 * * ? Fire every 5 minutes starting at 2 pm (14:00) and ending at 2:55 pm
(14:55), AND fire every 5 minutes starting at 6 pm (18:00) and ending at
6:55 pm (18:55), every day.
0 0-5 14 * * ? Fire every minute starting at 2 pm (14:00) and ending at 2:05 pm
(14:05), every day.
0 10,44 14 ? 3 WED Fire at 2:10 pm (14:10) and at 2:44 pm (14:44) every Wednesday in the
month of March.
0 15 10 ? * MON-FRI Fire at 10:15 am every Monday, Tuesday, Wednesday, Thursday and
Friday.
0 15 10 15 * ? Fire at 10:15 am on the 15th day of every month.
0 15 10 L * ? Fire at 10:15am on the last day of every month.
0 15 10 ? * 6L Fire at 10:15am on the last Friday of every month.
0 15 10 ? * 6L 2003-2006 Fire at 10:15 am on every last Friday of every month during the years
2003, 2004, 2005 and 2006.
0 15 10 ? * 6#3 Fire at 10:1 5am on the third Friday of every month.
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.
If you want to have the job run periodically, at a scheduled time, can remove the disabled="false"
property from the Cron Scripts via the Scheduler.
Permission Management
Useful reference information that helps you configure permissions and roles.
(See Configure user permissions and Configure user roles for more information.)
Permission 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
Permission configuration can be done for each project, so there can also be a project-scope
permissions.xml. The project-scope permissions.xml file is stored in PROJECT_FOLDER/.polarion/security/.
Note
When parsing permissions, Polarion checks the Project scope first. If none are specified in that scope,
it checks the Global scope.
User roles are roles that can be defined and assigned permissions by administrators.
You can access the list of user roles in: Administration User Management Roles
The following tables provide a high-level description of the default user permissions.
Tip
Polarion comes with the following predefined roles out of the box, but administrators can configure their
own global roles and permissions with a high level of granularity.
Tip
Administrators must define Project level user roles and permissions from scratch unless they use one
of the following of project templates with demo data.
• Project templates with demo data: (Drive Pilot, Drive Pilot QA, E-Library and Weather Station.)
• The following starter roles in the demo data templates are just to get you started. You can amend
them and even create Custom permission sets for a single artifact type by configuring new roles and
permissions.
Note
A user assigned this permission on the Global level, does not need to have the
project_admin role assigned in any project.
Note
Only users with the APPROVE/DISAPPROVE, APPROVE/DISAPPROVE as
ANOTHER USER permissions (or the project_approver role in the demo
templates) appear in the Approving User drop-down list in the Approvals panel.
project_assignabl Project-scope permission to have Work Items assigned. Users with this role appear
e in the pick list of users in the Assignee field of Work Items. By default this role
Dynamic roles are built into Polarion to control permissions for various Work Item and Document
operations.
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.
Note
Dynamic roles only work with permissions, not with workflow required roles.
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.
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.
a. A user is assigned both a project_user role and a project_assignable role in the Project
scope.
b. The project_assignable role gives them permission to edit (MODIFY) Work Items, but the
project_user role does not. (See screenshot below.)
c. 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.
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.
Consequently, you should be careful about how widely you assign that role.
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
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
The following fields do not have configurable MODIFY permission, and are therefore not modifiable by
users:
• Author
• Created
• Planned End
• Planned In
• Planned Start
• Updated
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- • If the user re-importing a round-trip document is denied MODIFY permission for fields
trip import 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.
Note
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.
In round- If the exporting user is denied MODIFY permission for some fields, those fields are read-only
trip export in the exported file.I
• Status
• All Custom Fields defined for Documents.
Tip
The Document-level MODIFY FIELDS permission is the parent permission for these field-level permissions.
This section lists the default enumeration configuration files, and the Work Item fields for which they
provide list item values.
Keep in mind that project templates may have different default configuration files for template-specific
Work Item types, fields, etc.
Tip
See Configure Enumerationsfor more information.
Repository scope
A list of event and targets for Notifications you can set in Polarion.
Tip
See Configure Notifications for more information.
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 topic list and describe key
notification events. In the configuration files, notification events are defined between <notification-
config></notification-config> elements, and notification targets are inside events. The following
events (and appropriate values of the <event_name> tag) are defined:
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:
Notification targets
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 two or more categories — both assignee and current user, for example — will receive
only one notification. 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 variables are available and can be referenced in configuration of custom notification
email subject lines.
Variable Description
$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.
Variable Description
$BUILD_STATUS$ Status of a build (failed, aborted, ok)
$BUILD_PROJECT_NAM Name of the project for which build was started.
E$
$BUILD_ARTIFACT_LAB Human-readable build artifact label (short description).
EL$
$BUILD_STAMP$ Build's time stamp.
$BUILD_BY_NAME$ Name of the user who started a build.
Variable Description
$USER_EVENT_NAME$ Name of an event — User Updated, for example.
$USER_NAME$ Name of the user who has been changed.
$USER_BY_NAME$ Name of the user who evoked the notification.
Variable Description
$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.
Variable Description
$MODULE_EVENT_NA Name of the module event triggering the notification.
ME$
$MODULE_NAME$ Name of the module that has changed.
$MODULE_BY_NAME$ Name of the user who evoked the notification.
Tip
See Configure Custom Fields for more information.
Basic types
Tip
Check out the custom field and enumeration configurations in the demo projects.
Enumeration types
The following enumeration types encapsulate data from Polarion into lists that can be specified as the
value for Enum type Custom Fields.
• UI Name - The type Name that appears in the pick list for Enum type custom fields in the Custom fields
editor in Administration.
(Document in the screenshot below.)
• 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.
• Tip
Not sure how to compose a Query?
1. You can use the Query Builder within your target topic. (The Collections topic for Collection
object enums, Test Runs for Test Runs, etc.)
2. Use Convert to text to convert your graphical query to text.
3. Paste the converted text into the Query field.
Whenever a Query is used (including none), the options you can select as values for the custom field
will only be from the current Project.
(Unless you select global-level objects like role, project or project group.)
• If there is a single enumeration, click its icon to jump to the configured hyperlink.
ID UI Name Data
@build ( + Build All Builds found by a Lucene query in the Query field of the
[QUERY] ) custom enumeration or the QUERY parameter in scripts or API calls.
(See the screenshot above.)
ID UI Name Data
@collection ( + Collectio All Collections found by a Lucene query in the Query field of the
[QUERY] ) n custom enumeration or the QUERY parameter in scripts or API calls.
(See the screenshot above.)
ID UI Name Data
If no Query is specified, it returns all Test Runs in the current Project.
@timePoint ( + Time All Time Points found by a Lucene query in the Query field of the
[QUERY] ) Point custom enumeration or the QUERY parameter in scripts or API calls.
(See the screenshot above.)
You can configure Polarion build management features in the artifacts.xml file.
This topic gives the basic file format of the artifacts.xml file to configure building
<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>
Learn how to automate Work Reports and the different parameters you can use to customize your report
automation.
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
Configuration example
<periodFinish></periodFinish>
</job>
This topic documents the workflow Conditions available for configuring the workflow for Work Items.
In the workflow configuration, one or more Conditions may be applied to a workflow Action, and/or to
one or more workflow Functions for an Action. When specified for an Action, if the Condition's terms are
not satisfied, then the Action is blocked, and the Work Item cannot transition to the target status. When
when specified for a Function, the Function will not be run if the Condition's terms are not satisfied,
which may in turn block the Action, preventing the status transition. For procedural information, see
Configure the Work Item Workflow.
Tip
Need a custom script for Workflow Functions and Conditions?
• See the Scripting SDK Guide & Examples document for more information.
Available at: https://[YOUR POLARION DOMAIN.com]/polarion/sdk/index.html
(Click on the Download SDK Guide & Examples link.)
• It contains scripting tips, examples, and help on migrating from Rhino or Nashorn.
• You can also download additional Polarion_scripting_examples.
Related topics:
ApprovalState
Tests whether all Work Item approvals have a specific workflow status.
Parameter:
commonApprovalState The status value to be tested for — approved or waiting, for example.
If omitted, the condition testes whether all approvals have the approved
workflow status.
AtLeastOneApprovedAndNooneDisapproved
Tests that at least one user has logged approval of the Work Item, AND that no user has logged
disapproval. This condition has no parameters.
FieldNonEmpty
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:
If true, the condition will be passed if the field is empty. If false, the condition will be
passed if the field is non-empty.
LinkedWorkItem
Checks, that there is at least one linked or backlinked item, optionally with a specific link role, and/or Work
Item type.
Parameters:
link.role Optional. The link role to check for, to satisfy the condition. Value is the ID
of a configured link role.
target.work.item.type Optional. The type of linked Work Item to check for to satisfy the condition.
Value is the ID of a configured Work Item type.
backlink Optional Values: true or false. If true, then only backlinks are
checked.
LinkedWorkItemsStatus
Traverses incoming and outgoing links of defined roles, and passes if all target Work Items have one of the
valid statuses.
Parameters:
back.link.roles Comma-separated list of link roles of incoming links to check for, to satisfy the
condition.
link.roles Comma-separated list of link roles of outgoing links to check for, to satisfy the
condition.
valid.states Comma-separated list of statuses. Parsed linked Work Items must all have one of
these statuses in order for this condition to be satisfied.
RoleCondition
Checks a list of user roles that users must have in order to satisfy this condition, and consequently invoke
the Work Item Action.
Parameter:
roles Comma separated list of role names. A user invoking the workflow Action must have at least one
of the specified roles.
ScriptCondition
Evaluates whether or not a specific workflow Action is available, or whether a specific workflow Function
will run, according to the return value of a custom script. For details, please see Scripted Workflow
Functions and Conditions > Script Condition.
This topic documents the available workflow Functions for configuring the workflow for Work Items.
Whether or not a function runs may be configured to depend on satisfying one or more Work Item
workflow Conditions. For procedural information, see Configure Work Item workflow.
Tip
Use the TriggerJenkins Function for a defined workflow Action that triggers a remote Jenkins Build.
Tip
Need a custom script for Workflow Functions and Conditions?
• See the Scripting SDK Guide & Examples document for more information.
Available at: https://[YOUR POLARION DOMAIN.com]/polarion/sdk/index.html
(Click on the Download SDK Guide & Examples link.)
• It contains scripting tips, examples, and help on migrating from Rhino or Nashorn.
• You can also download additional Polarion_scripting_examples.
AddDefaultApprovals
Adds default approvals for the Work Item. More specifically, it 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 approvers 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 approvers. All
users with a specified role are added to the Work Item when executing a workflow
action.
Changed Field
Changes the value of a 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:
ClearField
Parameter:
field.name ID of the field to clear. This field should not be a required field.
Note
The ClearField function will not work with the plannedIn field because it is actually part of a Plan, not
the Work Item.
CreateLinkedWorkItem
Creates a linked or backlinked Work Item using a specified type, link role, and a set of categories. The new
Work Item is assigned according to the configured Auto-assignment scheme.
Parameters:
type Required. The type of the new Work Item to be created. Value is the ID of a configured
Work Item type.
link.role Required. Link role of the link that will be created between the original and the new Work
Item. Value is the ID of a configured link role.
backlink (Optional). If specified with backlink true the Work Item is defined with a
backlinked role and created as a child.
If set to false (the default value) the Work Item is created as a parent.
categories Possibly required. Comma-separated list of IDs of the Categories to be applied to the new
Work Item.
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
Traverses incoming and outgoing links of having specified roles, finds all target Work Items, and checks
if they are in one of the specified valid states. Any Work Items that are not in one of the valid states are
transitioned to the target state, and optionally, some of their fields are cleared.
Parameters:
MarkWorkflowSignaturesAsObsolete
Removes all of the Work Item signatures signed on the statuses that precede the one you've defined it for.
Parameters: none.
For example, one or more approvers signed a workflow status, but the item subsequently needs
amendments that invalidate the signature(s). If this function is defined for, let's say the Reopen action,
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.
ResetApprovalsState
Resets all approvals for the current Work Item to the waiting state.
Parameters: none.
ScriptFunction
Invokes a custom script to perform some action or actions in conjunction with a workflow transition. For
details, please see Scripted Workflow Functions and Conditions > ScriptFunction.
SetDate
Sets the specified field to the current date OR date-time, depending on the type of that field.
Parameter:
field.name ID of the field have a date or date-time value set in it. The field specified must be of a type
compatible with a date type OR a date-time type value.
This topic documents the workflow Conditions available for configuring the workflow for Documents.
In the workflow configuration, one or more Conditions may be applied to a workflow Action, and/or to
one or more workflow Functions for an Action. When specified for an Action, if the Condition's terms are
not satisfied, then the Action is blocked, and the Document cannot transition to the target status. When
specified for a Function, the Function will not be run if the Condition's terms are not satisfied, which
may in turn block the Action, preventing the status transition. For procedural information, see Configure
Document workflow.
Tip
Need a custom script for Workflow Functions and Conditions?
• See the Scripting SDK Guide & Examples document for more information.
Available at: https://[YOUR POLARION DOMAIN.com]/polarion/sdk/index.html
(Click on the Download SDK Guide & Examples link.)
• It contains scripting tips, examples, and help on migrating from Rhino or Nashorn.
• You can also download additional Polarion_scripting_examples.
Related topics:
ContainsNoMatchingWorkItems
If the Document contains any Work Items matching a specified query, then the workflow action is
blocked.
Caution
The ContainsNoMatchingWorkItems workflow condition does not reflect the changes in Work
Items done in the same edit/save operation as a workflow change.
Parameter:
query A Lucene query for Work Items. If the query finds any Work Items matching the parameters, the
workflow action is blocked.
If the query finds any items that match, the condition is not satisfied and the action will not be
allowed to proceed.
FieldNonEmpty
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:
If true, the condition will be passed if the field is empty. If false, the condition will be
passed if the field is non-empty.
RoleCondition
Checks a list of user roles that users must have in order to satisfy this condition, and consequently invoke
the Document transition Action.
Parameter:
roles Comma separated list of role names. A user invoking the workflow Action must have at least one
of the specified roles.
ScriptCondition
Evaluates whether or not a specific workflow Action is available, or whether a specific workflow Function
will run, according to the return value of a custom script. For details, please see Scripted Workflow
Functions and Conditions > Script Condition.
This topic documents the available workflow Functions for configuring the workflow for Documents.
Whether or not a function runs may be configured to depend on satisfying one or more Document
workflow Conditions. For procedural information, see Configure Document workflow.
Tip
Need a custom script for Workflow Functions and Conditions?
• See the Scripting SDK Guide & Examples document for more information.
Available at: https://[YOUR POLARION DOMAIN.com]/polarion/sdk/index.html
(Click on the Download SDK Guide & Examples link.)
• It contains scripting tips, examples, and help on migrating from Rhino or Nashorn.
• You can also download additional Polarion_scripting_examples.
AddDefaultSigners
Adds users to a list of invited signers who must sign to approve transition to the specified target 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 parameter signedBy.roles is not specified.
signedBy.roles Comma-separated list of one ore more user roles — project_approver, for
example. Users assigned any of the specified roles are added as signers.
Mandatory if parameter signedBy.users is not specified.
signer.role Optional. Any meaningful string describing the organizational role of users signing
a Document. Example: Signed for Legal Department.
target.status.id Mandatory. ID of the target workflow status to which Document can transition
after the signature policy is satisfied. For example, approved for the Approved
status.
ChangeField
Changes the value of a 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:
ClearField
Parameter:
field.name ID of the field to clear. This field should not be a required field.
InvokeAction
Workflow transition is performed on all Work Items contained in the optionally filtered Document. If some
Work Item workflow action cannot be run for any reason, then the Document workflow action fails and the
user is informed.
Parameters:
MarkWorkflowSignaturesAsObsolete
Moves all workflow signatures in the specified states to state Obsolete; marks all verdict comments linked
to the signatures as resolved.
Can be used on a Document workflow action to reset/restart the review/signature process. Because
Document must be reworked, any current signatures should not apply to the new version.
Parameter:
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
Resets all Document signatures to invited status. For example, suppose invited signers declined to sign,
necessitating modification of a Document, and consequently a new round of reviews and signatures.
This function can be used on a Document workflow action that starts another round of the review/
signature process after signature was declined. Because the Document has to be reworked due to a
signature for the Mark as Approved action having been declined, signatures for that action need to be
reset.
Parameter:
target.status.id 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 the specified status will be reset. The function accepts only
single value as a parameter.
ScriptFunction
Invokes a custom script to perform some action or actions in conjunction with a workflow transition. For
details, please see Scripted Workflow Functions and Conditions > ScriptFunction.
SetDate
Sets the specified Document field to the current date OR date-time, depending on the type of that field.
Parameter:
field.name ID of the field have a date or date-time value set in it. The field specified must be of a type
compatible with a date type OR a date-time type value.
This topic documents the workflow Conditions available for configuring the workflow for Test Runs.
In the workflow configuration, one or more Conditions may be applied to a workflow Action, and/or to
one or more workflow Functions for an Action. When specified for an Action, if the Condition's terms are
not satisfied, then the Action is blocked, and the Test Run cannot transition to the target status. When
specified for a Function, the Function will not be run if the Condition's terms are not satisfied, which may
in turn block the Action, preventing the status transition. For procedural information, see Configure Test
Run workflow.
Tip
Need a custom script for Workflow Functions and Conditions?
• See the Scripting SDK Guide & Examples document for more information.
Available at: https://[YOUR POLARION DOMAIN.com]/polarion/sdk/index.html
(Click on the Download SDK Guide & Examples link.)
• It contains scripting tips, examples, and help on migrating from Rhino or Nashorn.
• You can also download additional Polarion_scripting_examples.
Related topics:
FieldNonEmpty
Tests whether a Test Run field is empty or nonempty. 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:
RoleCondition
Checks a list of user roles that users must have in order to satisfy this condition, and consequently invoke
the Test Run transition Action.
Parameter:
roles Comma separated list of role names. A user invoking the workflow Action must have at least one
of the specified roles.
ScriptCondition
Evaluates whether or not a specific workflow Action is available, or whether a specific workflow Function
will run, according to the return value of a custom script. For details, please see Scripted Workflow
Functions and Conditions > Script Condition.
This topic documents the available workflow Functions for configuring the workflow for Test Runs.
Whether or not a function runs may be configured to depend on satisfying one or more Test Run workflow
Conditions. For procedural information, see Configure Test Run workflow.
Tip
Use the TriggerJenkins Function for a defined workflow Action that triggers a remote Jenkins Build.
Tip
Need a custom script for Workflow Functions and Conditions?
• See the Scripting SDK Guide & Examples document for more information.
Available at: https://[YOUR POLARION DOMAIN.com]/polarion/sdk/index.html
(Click on the Download SDK Guide & Examples link.)
• It contains scripting tips, examples, and help on migrating from Rhino or Nashorn.
• You can also download additional Polarion_scripting_examples.
MarkWorkflowSignaturesAsObsolete
Moves all existing workflow signatures related to the Test Run to Obsolete state. For example, a Test
Run was performed and signed, but something has occurred resulting in a decision to perform it again.
Therefore, the workflow action transitioning the Test Run to the pending status should invoke this function
to mark previous signatures as obsolete.
Parameters: none.
SetDate
Sets the specified Test Run field to the current date OR date-time, depending on the type of that field.
Parameter:
field.name ID of the field have a date or date-time value set in it. The field specified must be of a type
compatible with a date type OR a date-time type value.
ScriptFunction
Invokes a custom script to perform some action or actions in conjunction with a workflow transition. For
details, please see Scripted Workflow Functions and Conditions > ScriptFunction.
It is possible that a workflow extension may be removed, resulting in a missing or invalid workflow
condition and/or function, which in turn impedes some workflow action or actions from proceeding.
This can occur, for example, when the XML configuration file is edited locally, and subsequently
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 them in the
following ways:
• Errors resulting from missing workflow conditions or functions are written to the main Polarion log file.
• An administrator using the Workflow Designer in Administration who attempts to edit a workflow
configuration containing missing conditions/functions receives a warning dialog box 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 associated transition will not be possible until the configuration is fixed.
• 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.
Tip
Need a custom script for Workflow Functions and Conditions?
• See the Scripting SDK Guide & Examples document for more information.
(Available at: https://[YOUR POLARION DOMAIN.com]/polarion/sdk/index.html)
(Click on the Download SDK Guide & Examples link.)
• It contains scripting tips, examples, and help on migrating from Rhino or Nashorn.
• You can also download additional Polarion_scripting_examples.
Developers often write scripts in scripting Widgets in LiveReport Pages, and for workflow Conditions
and Functions.
Warning
This applies to all the unblocking properties described below:
A script always runs with the privileges of the users on whose behalf the script is running.
(The user executing it or a specific impersonated user via the doAsUser method.)
If you must leverage these blocked methods in script jobs, script calls or Classic Wiki Pages, you can
allow the usage of specific methods by listing them via the following properties.
Caution: They open Polarion to potentially malicious scripts that can change user permissions (and
more) if executed by a user with elevated administrative privileges.
• Scripts deployed to Polarion must be coming from trusted users or subject to code review before
uploading them to Polarion.
• Permission to write reports should be granted only to trusted users.
• Reports, widgets, and macros deployed to Polarion must be coming from trusted users or subject to
code review before uploading them to Polarion.
There's a good reason the set of methods is blocked, so unblocking all methods via * is strongly
discouraged.
You can unblock methods in job script calls that are blocked by default by defining them in the following
property to the polarion.properties file.
com.polarion.scripting.job.allowedSecurityServiceMethods=
Examples:
• com.polarion.scripting.job.allowedSecurityServiceMethods=addGlobalRoleToUser
(addGlobalRoleToUser is allowed and other methods are blocked when called from scripts inside a job.)
• com.polarion.scripting.job.allowedSecurityServiceMethods=*
(All methods are allowed when called from scripts.)
You can unblock methods in script calls that are blocked by default by adding them to the following
property in the polarion.properties file.
com.polarion.scripting.allowedSecurityServiceMethods
Examples:
• com.polarion.scripting.allowedSecurityServiceMethods=addGlobalRoleToUser
(addGlobalRoleToUser is allowed and other methods are blocked when called from scripts.)
• com.polarion.scripting.allowedSecurityServiceMethods=*
(All methods are allowed when called from scripts.)
Some ISecurityService methods are restricted from use in Classic Wik Pages by default.
You can add exceptions to this restriction by listing the methods in the following property in the
polarion.properties file.
com.polarion.wiki.allowedSecurityServiceMethods
Example:
com.polarion.wiki.allowedSecurityServiceMethods=addGlobalRoleToUser,removeGlob
alRoleFromUser
In all workflow configurations, you can use ScriptCondition and ScriptFunction for workflow
conditions or functions that are defined via a custom script. The Groovy and JavaScript/ECMAScript
languages are supported. This topic provides reference details for both ScriptCondition and
ScriptFunction, and also describes the procedure for implementing custom scripts for workflow
conditions and functions.
Tip
Need a custom script for Workflow Functions and Conditions?
• See the Scripting SDK Guide & Examples document for more information.
Available at: https://[YOUR POLARION DOMAIN.com]/polarion/sdk/index.html
(Click on the Download SDK Guide & Examples link.)
• It contains scripting tips, examples, and help on migrating from Rhino or Nashorn.
• You can also download additional Polarion_scripting_examples.
ScriptCondition
Applicable for all workflow configurations — Work Items, Documents, and Test Runs. Evaluates 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. If the script returns Boolean value true, then the workflow action can
proceed.
Parameters:
engine The name of the scripting engine to use. Valid values: groovy for the Groovy engine, or js for
JavaScript/ECMAScript engines.
script The name of the script to run. The script file must be stored in the scripts folder of the Polarion
installation's file system. See Script implementation, below, for specific path.
For example, given the existence of a Javascript script containing the line
"Test".equals(workflowContext.workItem.title); The workflow condition will be satisfied if
the title of the Work Item is "Test".
Administrators of Linux systems will require Owner, User and Group privileges, and be set up as a Polarion
System User.
ScriptFunction
Invokes a custom script to perform some action or actions in conjunction with a workflow transition.
Applicable for all workflow configurations — Work Items, Documents, and Test Runs.
Parameters:
engine The name of the scripting engine to use. Valid values: groovy for the Groovy engine, or js for
JavaScript/ECMAScript engines.
script The name of the script to run. The script file must be stored in the scripts folder of the Polarion
installation's file system. See Script implementation, below, for specific path.
Administrators of Linux systems will require Owner, User and Group privileges, and be set up as a Polarion
System User.
//create a comment
workitem.createComment(com.polarion.core.util.types.Text.plain(comment),titl
e,null).save();
/**
* Defines name for the created baseline.
*/
function createName(){
return baseObject.getEnumerationOptionForField("status",
workflowContext.getTargetStatusId()).getName();
}
/**
* Defines description for the created baseline.
*/
function createDescription(){
return "Created automatically by a workflow transition";
}
On-demand Work Item Loading dramatically improves the response time when editing large Documents
which contain main Work Items. Because it only loads the Work Items that are scrolled into view, it makes
editing large Documents more fluid and user-friendly.
On-demand Work Item Loading is enabled by default, for Documents containing 200 or more Work Items.
Administrators can set system-wide behavior by editing the following property in the polarion.properties
file.
Users can enable or disable it for individual Documents in the Document sidebar.
com.siemens.polarion.ui.document.lazyLoad.enabledByDefault=200
• 200 - The default setting. Enabled for all Documents containing 200+ Work Items. (Administrators can
set any numerical value.)
• true - Will enable it by default for all Documents.
• false - Will disable it by default for all Documents.
Limitations
• When On-demand Work Item Loading is turned ON, make sure that all the Work Items you wish
to copy have finished loading before pasting them somewhere else within the same Document. (This
limitation does not apply when copying them to a different Document.)
• Caption numbers are sometimes replaced with "#" while viewing the document in Polarion. The "#" are
replaced with the correct numbers when the document is exported. See the Caption reference topic for
details.
• Because On-demand Work Item Loading items are loaded from baselines, Calculated Fields will not
be visible in a Document when On-Demand Work Item loading is enabled.
(They will still be visible in the Work Item Properties Sidebar and the Work Item Editor.)
On-demand Work Item Loading can be set to ON or OFF for a single Document in the Document
Properties sidebar of the Document Editor. For details, see the User Guide topic Document Properties.
This topic 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.
• Linux: /opt/polarion/data/logs/main
• Windows: C:\Polarion\data\logs\main
Tip
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.
Apache log4j is used for logging. Its configuration file can be found at: [POLARION_HOME]/polarion/
plugins/com.polarion.core.util_*/log4j2.xml.
Caution
The Log4j configuration file and its formatting were changed in Polarion 22 R1.
The old log4j.properties configuration file is now ignored, and new configurations must be applied to the
log4j2.xml file in the new formatting.
• Old: log4j.logger.com.polarion.subterra.index.impl.ObjectIndex=DEBUG
• New: <Logger name="com.polarion.subterra.index.impl.ObjectIndex"
level="debug" />
The paths above are Linux examples. For Windows, substitute forward slashes (/) for the backslashes (\).
The following additional log files are configurable on both Windows and Linux platforms:
• Windows: C:/Polarion/data,
• Linux: The location varies depending on the Linux distribution installed.
Installation log files store information about the installation process. If you should experience problems
with installation you can provide these files to your Support Center engineer. Installation logs are written
to the following locations by default:
• Windows: C:/Polarion/data/logs/install/*.log,
• Linux: /var/log/polarion/*.log
Polarion log files are rotated on weekly basis. Apache log files are rotated as follows:
You can periodically remove old log files to optimize disk storage space on the server. For information,
please see: Cleanup of old log files.
Logging API
If you want to log additional information in Polarion logs (for example, from a custom extension), use the
Polarion logging API to avoid compatibility issues in future Polarion updates.
com.polarion.core.util.logging.ILogger
Example
import com.polarion.core.util.logging.ILogger;
import com.polarion.core.util.logging.Logger;
...
...
// declaration
ILogger logger = Logger.getLogger(Some.class);
...
// invocation
logger.debug("This will get logged at DEBUG level.");
...
The schema for Polarion's XML Export feature 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.
The schema for Polarion's XML Export feature 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. Refer to this schema for any custom XSL templates you may create to
use with XML Export.
Note
You can copy the xml below or download the XML export schema as a file.
<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: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="workItems">
<xs:complexType>
<xs:sequence>
<xs:element name="workItem" minOccurs="0" maxOccurs="unbounded"
type="WorkItem" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
This topic lists the default set of internally defined Work Item metrics for projects contained in the
workitem-metrics.xml configuration file.
Caution
These metrics are deprecated and scheduled for removal.
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: Work Item Metrics.
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%}
This topic documents facts that can be displayed in dashboards and the calculations that can render them.
Caution
These calculations and facts are deprecated and scheduled for removal.
Fact bases
Polarion fact bases store data for various audit and metrics calculations.
processaudit/project-level/source-check-aggregate
repo-analysis:
• 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.
• 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
These parallel fact bases with trend data exist for each regular fact base listed in the previous section.
workitems-trend-data
repo-trend
Available values: Trends of particular values from the repo-analysis fact base.
processaudit/project-level/source-check-aggregate-trend
Available values: Trends of all values (and their properties) from the processaudit/project-level/source-
check-aggregate fact base.
• test-coverage.ratio: test coverage (i.e. ratio of total lines of code to line of code covered by unit tests)
Polarion provides a few default macros implemented in Velocity that address, for example, the display of
signatures in LiveDocs.
[POLARION_HOME]/polarion/plugins/com.polarion.alm.wiki_N.NN.N/src/main/webapp/templates/
macros.vm
Note
Path above is Linux style. For Windows, substitute backslash characters (\) for the forward slash
characters (/).
Each of the sections is implemented as a specific sub-macro. For example, if you want to customize a
macro such as documentPanel, you can refer to the following definition:
#renderLastApproved($approvedState)
#renderSignatures($showPending)
</div>
#end
You can use Velocity scripting to render dynamic content in Classic Wiki Pages, LiveReport Pages, and
LiveDocs.
The following table lists the Apache Velocity variables available during rendering of pages containing
dynamic content rendered with Velocity. Developers may use these for extending Classic Wiki pages,
LiveReport Pages, and dynamic Velocity-rendered content in LiveDocs, via the respective Polarion API
classes and interfaces. Descriptions of classes and interfaces are available in the Javadoc provided with the
API.
Note
Velocity variables and Page parameters can be used in PDF header/footer configurations, but only for
Classic Wiki pages.
Polarion uses an implementation of the Apache Lucene query engine to enable portal searches and Work
Item queries.
This section documents some properties which System Administrators can set in the polarion.properties
system configuration file to control some behaviors of the embedded Lucene.
Default
Property Description Value
luceneMaxClaus Defines how many OR/AND parts a query 20000
eCount 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 (thousands).
luceneMaxField Defines the maximum number of terms 50000
Length 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 (description, for
example). A 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".
The License topic lets you view license information, such as the maximum number of users and current
available licenses in your pool.
The License topic in Global Administration displays the following license usage information:
Concurrent license
Column Description
Total Maximum number of users that can access Polarion at the same time with a
Concurrent license assigned.
Configured The number of users configured in the users file that can share 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.
Note
The Peak value resets when you restart your Polarion instance.
Named license
Column Description
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 that are not assigned to a user.
Expiration Date Expiration dates of the Base and Add-on licenses
Tip
The server-based Add-on licenses appear only in the Concurrent license Usage Overview section.
The Total/Configured values are shown as ‘1’, and the Free/Peak values are shown as ‘0’.
Usage details
Column Description
User The user ID of a user who is currently using a license.
Status Status of the license used by Status
Tip
See the Quick Help section on the License Assignment and Usage administration page and the
Specify license assignments section for more information.
Related Topics
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, as
described in 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.
Note
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 -newkey rsa:1024 -keyout privateKey.key
-out serverCert.pem
The SDK content is installed to the file system along with all other programs and data. You need to explore
the file system of your installation in order to access it. You may wish to copy the SDK from the installed
location to developers' local computers, or host it on a file server on your network.
The [POLARION_HOME]/polarion/sdk/index.html file provides links to all SDK resources. You can
access the SDK index page via your web browser by appending polarion/sdk/ to the URL of your
Polarion server.
Example:
http://polarion.mydomain.com/polarion/sdk/
Tip
Need a custom script for Workflow Functions and Conditions?
• See the Scripting SDK Guide & Examples document for more information.
Available at: https://[YOUR POLARION DOMAIN.com]/polarion/sdk/index.html
(Click on the Download SDK Guide & Examples link.)
• It contains scripting tips, examples, and help on migrating from Rhino or Nashorn.
• You can also download additional Polarion_scripting_examples.
[POLARION_HOME] (definition)
Denotes the root of the Polarion installation in documentation. For Windows systems, the default value is
C:\Polarion. For Linux systems it is the location of the binaries, usually /opt/polarion/.
Administration
The area of Polarion used by administrators for managing the system configuration, customization, user
accounts, and so forth. Access requires administrator permissions on the user's account. Permission may
be granted globally for the repository, or for one or more specific projects. When a user account has the
required permission for the scope, the Administration link appears in the Polarion header enabling the
user to access administration topics and features.
Artifact
A piece of information that 1) is produced, modified or used by a process, 2) defines an area of
responsibility, and 3) is subject to version control. An artifact can be a model, a model element, or a
piece of information that is used or produced by a software (or application) development process.
In Polarion documentation, the term can apply to Work Items. It is generally applied to units of blocks of
information in an external office document which become Work Items when the document is imported
into Polarion.
Baseline
• Project Baselines let you to go back in time and browse, search, view, or run reports in a Project
Baseline just as if the baseline was the current project state.
• Document Baselines let you mark and label a specific Live Document save (revision) in a
Document's history.
• Collection Baselines place a marker in a Collection's history so that you can always refer back to the
Collection's state at important milestones.
Bi-directional Traceability
Achieved when the traceability chains can be demonstrated in both directions, ensuring that the end
product meets all of the requirements, and only the requirements specified.
Build Artifact
The smallest buildable entity. Comprised of resources - usually source code and support files.
Category
A standard data field of Work Items for the purpose of categorizing them. When Work Items are assigned
one or more Category values, they can be queried by Category. For example, if category User Interface is
defined, Work Items relating to user interface development can be assigned that category. It is then simple
to query for Work Items having a Category value matching that "User Interface".
Categories can be defined for each project in Administration Work Items Categories.
Classic Wiki
See: Wiki Page.
Content Pane
Content Pane is a part of user interface, where you can read project information (wiki pages or Work Items,
for example) and edit content.
Dashboard
A special wiki-based page that rolls up and displays key status information based on actual progress data
automatically maintained by Polarion. Information can be viewed for an entire repository, a group of
projects, or a single project.
Document
Document (capitalized) in documentation refers to a Live Document.
Enumeration
A list of values that users can select from and apply to some Work Item field. For example, Work Item types
are defined in an enumeration (Administration Work Items Enumerations).
Info Page
A type of Page that does not contain user-configurable report Widgets which retrieve display project and
Work Item data. The term is simply to distinguish such Pages from LiveReport Pages that do contain
Widgets. Technologically, there is no difference. A Page created as an Info Page can contain Widgets.
Information Scope
Polarion enables viewing and management of information for an entire repository, for a group of projects,
or a single project. The information scope refers to the breadth of information you are currently working
with. The Repository scope means just that: you are working with or looking at information from all
projects in a repository. For example, the Dashboard topic in this scope (not shown by all licenses) rolls
up status information from all projects to provide a view on the overall status of development across all
projects managed with Polarion.
Interface
A named version of the Polarion user interface that displays some subset of all available information to
facilitate some role or work context, for example, "Manager" or "Developer". An Interface can show or hide
Navigation topics, invoke some particular view on Work Items, show or hide Work Item fields, and control
the layout of Work Item fields.
Job
A predefined system process that may be initiated either by system or by user. Examples of jobs include
backups and builds. Administrators can define jobs and job scheduling.
Link Role
A descriptive word or words applied to a link between two Work Items that describes the relationship
between those items. For example, a link role "depends on" may be defined and applied to a link between
two Work Items when one of the linked items has some dependency upon the other one.
LiveDoc
An artifact-aware online document that can contain Work Items of one or more types. LiveDocs, (referred
to in documentation as "Documents") are ideal for creating specifications for such things as requirements
or test cases. Work Items defined in a LiveDoc can be managed in the same way as those defined directly in
the integrated tracker (that is the Work Items topic in Navigation).
Live Document
See LiveDoc above.
Live Plan
A legacy feature that automatically calculated a project plan based on a number of input parameters
including project start and end dates, Time Points and Work Items assigned to them, estimated time and
time worked on Work Items, human capacity based on working calendars, and various other factors. The
information was rendered into a graphical chart based on the GANTT chart.
The feature was deprecated, and replaced by Plans. Because the chart component was based on Adobe
Flash, the feature was removed from Polarion in the 21 R1 release after Flash support was dropped by all
supported browsers.
LiveReport
A type of Page that contain user-configurable report Widgets which retrieve display project and Work
Item data. The term is simply to distinguish such Pages from others that do not contain Widgets.
Technologically, there is no difference.
Module
A Module was a special container for Work Items in Polarion versions prior to version 2011. It is now
deprecated in favor of Polarion LiveDoc Documents.
Navigation Pane
The Navigation pane is the part of user interface where a user is able to select available topics the present
features, functionality, and information.
Page
When capitalized, refers to a portal web page that contains information that is not tracked and workflow-
managed through a process.
Content of Pages cannot be marked and managed as Work Items. However, Pages may display Work Item
data via special report Widgets. Pages can have hyperlinks to other internal and external URLs. Pages have
a palette of rich formatting tools, and can display images and contain file attachments.
Process
A set of repeatable steps with a clearly defined beginning and end.
Project
An undertaking requiring effort that is constrained by limited resources, and is planned, executed, and
controlled.
In Polarion, the term can also refer to a folder in a Polarion repository that stores and manages all artifacts
relating to some specific development activity or goal. A project's folder is marked as a project by Polarion
when an administrator creates a new project.
Repository
Polarion's underlying data storage and versioning mechanism. Currently, the open-source version control
system Subversion is used for this purpose. All development artifacts including Work Items, Wiki Pages
and Documents are stored and versioned in the repository.
By default, a single internal Subversion repository is created when Polarion is installed, but you can also
configure additional External Repositories.
The Clustering feature lets you run Polarion on multiple servers, either physical, virtual, or a combination
of the two. The topography can be set up to host multiple servers running on separate machines each with
its own Polarion repository, and/or multiple machines all accessing a single Polarion repository. (Polarion
servers on any node can optionally be configured to access external repositories.)
Note
Special installation and configuration procedures beyond the scope of Help documentation are required
to set up a clustered multi-server environment. These are covered fully in the Deployment and
Maintenance Guide document, available in Polarion's Documentation page on Support Center
Requirement
A specific business result that is needed to solve a problem or achieve an objective.
In Polarion, the term often refers to an artifact or Work Item type which defines a requirement as per the
definition above.
Saved Query
A query string either manually entered or built by the Query Builder which is saved for later reuse. Saved
queries appear in the drop-down panel of the Query Builder in Work Item views in the Work Items topic.
Saved queries can be shared globally for all platform users, or for all users of a specific project. Individual
users can also create "private" saved queries which are available only to them.
Saved Queries differ from Shortcuts in that they only retrieve Work Items and are available only in the Work
Items page.
Shortcut
A special link in Navigation that takes the user to specified saved subset and presentation of information.
Shortcuts can be shared globally for all platform users, or for all users of a specific project. Individual users
can also create "private" shortcuts which are only available to them.
Shortcuts differ from Saved Queries in that they are not limited to retrieving Work Items, and they can
retrieve presentation as well as data.
SVN
An abbreviation for Subversion, a leading open source version control system used by Polarion to store all
artifacts of the application development process.
Test Case
A type of Work Item which defines a set of steps for testing some defined functionality or feature of
an application. Polarion project templates which provide QA/testing support predefine a Work Item type
named "Test Case". (Project administrators may change the actual name of this type, or create some other
type which is analogous to it.)
Test Case items may created and defined either in a Document or directly in the integrated tracker
(Navigation Work Items).
Test Run
A business object which encompasses a set of Test Cases (which usually define manual tests) or unit
tests (normally automated tests) to be executed, together with information about the status of the Test
Run, results of execution of the Test Run and the Test Cases or unit tests which it encompasses, the test
environment, and the build tested.
Time Point
A named milestone or development deadline associated with a date. Time Points are most commonly
created for projects by a project manager/administrator. Work Items can be assigned to a Time Point by
project managers or other users with the necessary permissions. The field can be included in queries for
reporting purposes.
Variant
For a glossary of terms related to variants and variant management, see Terminology.
View
A named representation of a set of Work Items in which the retrieved items are presented in some specific
format or context. For example, the Table view renders Work Items as table, the Tree view renders Work
Items as a hierarchical tree of linked items, the Matrix view renders two sets of Work Items in a matrix
format. The Road Map view renders Work Items associated with a defined point in time.
Widget
A user-configurable visual report component that can be inserted into LiveReport Pages and which
retrieve and visually format project and Work Item data in useful ways in real time.
Wiki Page
DEPRECATED. A unitary online document that uses Polarion's initial wiki technology from prior to version
2015. Now referred to in documentation as "Classic Wiki page".
Content of Wiki Pages cannot be marked and managed as Work Items. However, Wiki Pages may display
Work Item data from the integrated tracker by means of macros which contains query language that
retrieves some set of Work Items and dynamically displays it in a Wiki Page. Pages can have hyperlinks
to other Pages and/or external URLs, and/or to tracker pages. Pages can display images and contain file
attachments.
Work Item
Polarion's term for a tracked and managed system artifact that represents some issue to be processed, or
element of work to be done. Work Items are a key element in the workflow of a project.
• Defect
• Change Request
• Requirement
• Task
Administrators can create custom Work Item types to support any process, semantics, and workflow.
Workflow
The feature of Polarion that encapsulates a process and subsequently controls and automates the progress,
and reflects the status of Work Items from their inception until they are resolved/closed.
Polarion comes with predefined workflows suitable for many types projects. Administrators can customize
workflow to support any process or methodology used by an organization to develop applications.
Workflow Action
An action invoked by a user or a job that changes the status of a Work Item. For example, suppose a project
has statuses Open and Accepted defined for Work Items. Suppose also that it has a workflow action Accept
defined. When set by a user, the Accept action triggers transition of the Work Item status from Open to
Accepted.
Workflow Transition
An artifact defined for Work Item workflows which transitions them from one defined status to another
(from Open to Accepted, for example), resulting in notifications, history entry, etc.
Work Record
A multivalued data field for Work Items. It enables the assignee(s) of a Work Item to record multiple blocks
of time spent working on the item. The aggregated time from all work records is added to any value in
the Time Spent field, and that value is used to update the Remaining Estimate field. Using Work Records is
optional.
Polarion may work with other browsers, but only those listed here have been tested and certified as
supported.
Polarion displays a warning message to users who log in using an unsupported browser.
Here are some links to the product web site which may be of interest:
Selecting Polarion Student Edition after installing the trial gives students the following:
• Up to 20 named users.
• A license valid for an entire year.
• Can create three new projects. (On top of the included demo projects.)
• Up to 1000 Work Items. (Across all projects.)
Note
• Students must acknowledge that the Polarion Student Edition will only be used for non-commercial
academic purposes in accordance with Siemens EULA.
• Look for the Polarion entry on the Siemens Digital Industries Student Software portal for more
information.
COPYRIGHT STATEMENT
This software and related documentation are proprietary to Polarion AG (a Siemens Digital Industries
Software company).
Siemens and the Siemens logo are registered trademarks of Siemens AG. NX, Solid Edge, and Teamcenter
are trademarks or registered trademarks of Siemens Industry Software Inc. or their subsidiaries in the
United States and in other countries.
All other trademarks, registered trademarks, or service marks belong to their respective holders.
Polarion software products use icon images from the Silk Icons set, and the Copenhagen icon set.
Polarion software products may use licensed icon images from the Glyphish PRO icon set.