=============
Configuration
=============
This file contains important information that you should be aware of before
updating to a new release. It describes changes that may impact your current
system, and may include additional recommended actions to take before or after
updating Polarion. If you have not yet read README.txt (in the same folder
as this file), please review it before proceeding.
Information below is grouped according to the Polarion version in which it was
introduced. Please process any actions down to the version from which you update.
Some actions may be noted as specific only for some Polarion products.
=======
General
=======
This section contains general points that you should check during the update:
* The Resource Traceability feature is enabled by default and the RT server starts automatically with Polarion.
Add the following property with a "false" value to disable the Resource Traceability feature:
"com.siemens.polarion.rt.startRtServer=false"
If you decide to use Resource Traceability, a certificate must be imported into your Polarion Java TrustStore.
To point Polarion to your TrustStore, use the following property:
"-Djavax.net.ssl.trustStore"
If your organization does not have a TrustStore, importing the certificate to the Java Key store will also work.
See the "Importing a Certificate to the Java Keystore" section in Help for details.
* If you use a customized log4j.properties file, alongside the polarion.properties file,
please consider merging it with the new default log4j.properties version the org.apache.log4j plugin.
* If you have installed the Polarion VARIANTS Server Add-on, it must be updated to the
current version AFTER updating your Polarion installation. Please follow
the instructions included in the HOW_TO_INSTALL_THIS_UPDATE.txt, bundled in the update distribution.
=============
Version 20 R1
=============
* Maven central repository is no longer accessible by plain HTTP (see https://support.sonatype.com/hc/en-us/articles/360041287334). Because Maven bundled with Polarion
uses plain HTTP it is necessary to add following into [POLARION_HOME]/maven/settings.xml (just before the closing tag):
https-central
https://repo1.maven.org/maven2
central
* Polarion 20 R1 has a new Collection feature.
To start using Collections in your existing projects or projects based on custom project templates,
administrators will first need to:
1. Enable the Collection Topic in Polarion's Navigation.
2. Create the necessary folders in the repository and grant read and write access.
See The Administrator's Guide > Configure Collections topic in Polarion's online Help for detailed instructions.
Note: For new projects based on Polarion's built-in templates, Collections are preconfigured and work out-of-the-box.
* The com.polarion.portal.jetspeed plug-in has been removed.
If you use an extension that depends on this plug-in, its transient dependencies should be updated manually.
* PostgreSQL 11.4 is now supported, and bundled in the update distribution. Version 9.4 is still supported, but updating to
this version is recommended.
IMPORTANT: The update script for Windows does not update PostgreSQL. Administrators need to do this manually on Windows systems.
For information and basic update steps, see the bundled "Third-party_for_Windows.txt" file, "Updating to the Bundled Version of PostgreSQL".
* The way Attachment content indexing is done has been changed. As a result, search results before the update may differ from those conducted after the update.
(Administrator's should inform their users accordingly.)
What has changed:
The hardcoded list of file extensions that are not indexed (consisting of mainly media files), was replaced with a default list of file types that are.
This new list of file extensions can be reduced or extended via configuration properties in the polarion.properties file. See the "Attachment file types for indexing"
section in Polarion Help for more information.
* H2 databases are no longer supported. Polarion requires a correctly configured PostgreSQL database to start.
* 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 https://maven.apache.org/repository-management.html for more information on repository managers).
*WARNING!
SVN versions 1.10.x and 1.11.x have an issue with Groups defined in the AuthZ file that don't have an associated account. (This issue was resolved SVN 1.12.0)
For new Polarion installations:
The following property is added automatically and set to "false":
com.polarion.platform.repository.canHaveEmptyRolesInSvnAccessFile=false
A dummy user is automatically assigned to every Group. (It's only visible in the svn access file.)
IMPORTANT!
Do not delete this dummy user (ID=KF9Nrsnp9Ad) in the svn access file or create a user with the same name.
For existing Polarion installations:
If you update your Linux distribution to a version that contains SVN (1.10.x - 1.11.x) you should either:
a) Add the following property to the polarion.properties file and manually assign a user to all Groups in the AuthZ file:
com.polarion.platform.repository.canHaveEmptyRolesInSvnAccessFile=false
b) Check whether your selected Linux distribution has already incorporated the patched SVN. (1.10.6 - 24 July 2019 and onwards)
See the "Required third-party software components" section in the "Appendix" chapter of the Linux install guide for details.
- An HTML version of the guide can be found at: https://polarion.plm.automation.siemens.com/documentation/latest
* In 20 R1 we disabled the TLS 1.0 and 1.1 protocols in the Apache config for Windows installations.
(All major browsers stopped support for them H1 2020.)
* A new property has been introduced that sets the maximum pool size for PostgreSQL connections:
com.siemens.polarion.platform.sql.maxPoolSize
The following rules are used if the value is not defined:
If the number of processors * 2 is less than 10, the value used is 10.
If the number of processors * 2 is more than 20, the value 20 is used.
If the value is defined, the following rules apply:
If the defined value is less than 10, the value 10 is used.
If the value is more than 20, the user MUST adjust the max_connections value in the PostgreSQL server configuration to a number that's more than 4 times the value used.
* IMPORTANT:
The File protocol for the "repoSystem" property is no longer recommended and might not work due to an issue with SVNKit.
We recommend that you use the SVN protocol for improved performance.
See the Optimize Subversion in Polarion Help for details on how to set it up.
(User and Administration Help > Administrator's guide > Advanced administration > Optimize Subversion)
If you choose to stay with the file protocol (not recommended), then make sure that "repoSystem" is set to the following:
For Windows: (Use three slashes instead of two.)
repoSystem=file:///$[com.polarion.root]/data/svn/repo
* JIRA CONNECTOR: Changes to existing Jira mappings may be required. If you use the Polarion Connector for Atlassian Jira,
and you have existing mappings to Jira Cloud, you will need to update such mappings due to a recent change in the Jira Cloud API.
The "name" field of the "User" object is not present now, and is replaced by field "accountId". You can make this change in your
existing configuration(s) by editing the relevant Sync Pair(s) in Polarion project Administration, or in the underlying
configuration file /.polarion/synchronizer/configuration.xml.
IMPORTANT: On-premise installed versions of Jira are NOT affected, and no change to your existing mappings is necessary.
You can check the Jira instance type at: /rest/api/latest/serverInfo
* For on-premise versions: "deploymentType": "Server"
* For Cloud versions: "deploymentType": "Cloud"
Fields "accountId" or "name" can be retrieved from: /rest/api/latest/user/search?username=
For additional information see:
https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/#user
============
Version 19.3
============
* Work Item extensions now load asynchronously by default.
(If an extension integrates with a third-party tool like GitLab and there's a connection issue on their end, the rest of the Work Item's content will still load.)
If your custom extensions conflict with this new default setting, you can disable it by adding the following property to the polarion.properties file:
com.siemens.polarion.ui.synchronousFormExtensions=true
Note: This is a temporary measure. The ability to disable this feature is expected to be removed in future releases,
so you should identify and address any issues with your custom extensions before then.
* Parts of each user's 'remember me' password are now stored in individual files for each user in a new 'rememberme' folder.
For cluster and Multiple Stand-alone Instance installations, the 'rememeberme' folder is located on the Coordinator file system and stores information
for all nodes and clusters. The 'remember_me_pass.properties' file that was formerly stored in the 'ui-data' folder on the shared file system for cluster
and Multiple Stand-alone Instance installations, or locally for local installations is no longer needed and can be removed.
* Control Charts now determine "Work Days" based on the "Working Calendar" defined in Polarion.
(Global Administration > Work Items > Working Calendar)
Prior to 19.3 Control Chart "Work Days" were hardcoded as Monday to Friday.
(If the current Working Calendar is different, your Control Charts will update accordingly.)
============
Version 19.2
============
* The Zookeeper's transaction logs are now automatically purged from the Coordinator's data folder.
By default, the logs are purged once every 24 hours and only the three last snapshots and their corresponding logs are retained in the data folder after a purge.
This functionality can be disabled or configured with the following two properties in the polarion.properties file:
com.polarion.zookeeper.logsPurgePeriodMins=1440
The time interval, in minutes, to purge the Zookeeper's transaction logs from the data folder. (Set to 0 to disable.)
com.polarion.zookeeper.retainedSnapshotsNum=3
The number of snapshots and their corresponding logs retained in the data folder after a purge. All others will be deleted. (Must not be lower than 3.)
============
Version 19.1
============
IMPORTANT!
* Polarion UI data in Cluster and Multiple stand-alone instance deployments is in a new location.
You must migrate existing UI data so that it works with the latest version of Polarion.
To migrate the UI data:
1. Create the following directory: "[POLARION_DATA]/workspace/cluster-data/[CLUSTER_ID]/" on the Coordinator for each configured cluster or stand-alone instance.
([CLUSTER_ID] is the value for the com.polarion.clusterId property in the polarion.properties file.)
2. Move the entire "ui-data" directory and all its subdirectories and files from the shared storage (for clusters) or from all stand-alone instances:
From: "[POLARION_DATA]/workspace/" (The default shared file system directory.)
To: The new directory (or directories) that you created in step 1. ([POLARION_DATA]/workspace/cluster-data/[CLUSTER_ID]/)
============
Version 19
============
* Polarion now only supports OpenJDK 11. (Oracle's Java SE Development Kit 8 is no longer supported.)
IMPORTANT!
When installing or upgrading to OpenJDK 11 make sure the default file encoding matches the same encoding used by the previous version of Java.
To make sure that the file encoding is correct:
1. Search for the file.encoding property in the main log file (C:\Polarion\data\logs\main\).
2. If the default file encoding for the new Open JDK 11 differs, then define it explicitly as a Java Runtime property by adding the following property,
with the file encoding you deploy, to the polarion.ini file. (C:\Polarion\polarion\polarion.ini by default).
Dfile.encoding=file_encoding
(Replace "file_encoding" with the one you use.)
3. Reinstall the Polarion service (run service.bat) for the Java Runtime property to take effect.
* The Rhino Engine https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino will also be completely removed in future versions of Polarion.
* Important notice regarding the Workflow Signatures:
Refinements and improvements have been made to the Workflow Signatures feature introduced in 18.2 that require some configuration adjustments if it has already been implemented.
1) Required adjustment:
Remove the "$user" variable from the following property:
secure.approvals.comment=
(The current user is now automatically inserted and if you don't remove $user, then it will appear as "$user" in the approval comment.)
2) Additional variables were added to the following property:
secure.approvals.comment.onBehalfOf=put your custom comment text here
In addition to custom comment text, this property also supports a verdict variable ($verdict) and a verdict image ($img).
3) New property:
secure.approvals.comment.text=put your custom comment text here
You can now add custom approval verdict text.
See the following section in Polarion's help for more information:
Administrator's Guide > Configure Work Items > Configure Work Item Workflow > Workflow for Approvals > Enable Electronic Signatures Support
============
Version 18.3
============
* The Eclipse platform plug-ins (sometimes referred to as bundles) that are part of Polarion were updated from version 3.1
to 4.8 (aka Photon). Although this should not impact most custom extensions,
some might need to be migrated to ensure that they're still usable after the update.
This should only affect extensions that take the form of a plug-in. (Located in the polarion/extensions folder in the Polarion installation directory).
There are two potential causes for incompatibility:
1) Plug-ins without an OSGi bundle manifest (META-INF/MANIFEST.MF) are no longer supported.
In the old Eclipse platform, the runtime dependencies of a plug-in could be specified in the plugin.xml file.
This approach was already deprecated in the 3.1 version that was part of Polarion prior to this update,
so it should not affect existing custom extensions.
NOTE: The plugin.xml file is still used to contribute to plug-in extensions, but it can no longer be used to specify dependencies between pug-ins, runtime libraries etc.
2) Parts of the Eclipse platform API have been removed since version 3.1.
Plug-ins that make use of the Eclipse platform API (e.g. contain a plug-in activator class or provide extension
points), might require changes. Please follow the instructions in the JavaDoc for the Eclipse platform classes that are used.
For additional information, please see the "Platform Plug-in Developer Guide" for Eclipse Photon at: https://help.eclipse.org/photon/nav/2
If you need help with the migration itself, please contact Polarion's technical support at: http://www.siemens.com/gtac
* Support for Oracle's Java SE Development Kit 8 is being phased out in favor of the open source alternative (OpenJDK 11).
Polarion 18.3 supports both Oracle's Java SE Development Kit 8 and OpenJDK 11 but it will be the last Polarion release that supports both.
Polarion 19 (scheduled for release in the spring of 2019), will only support OpenJDK 11, so administrators should plan accordingly.
NOTE: If you've added extra GC-related runtime parameters for Java, you will need to update them accordingly for Java 11.
(The JVM may fail to start with Java 8 style GC options.) See the "Update Java" section in the Windows Installation guide for details.
a) The PDF version can be found in your Polarion installation folder.
b) HTML and PDF versions can be found at: https://polarion.plm.automation.siemens.com/documentation/latest
* Installing a new extension now requires an additional step, described in the [INSTALL]/polarion/extensions/README.txt file. This file is updated automatically when installing the update.
============
Version 18.2
============
* New and existing Polarion installations:
If Workflow Signatures were set as mandatory in the workflow configuration of your existing installation, after the Polarion update
your old Workflow signature comments will be preserved and still visible in the "Comment" section.
All new signed workflow transitions will appear in the new "Workflow Signatures" section on the Work Item form. For both new and existing Polarion installations
you need to add the new "Workflow Signatures" section to the "Form Layout" configuration so that it appears in the Work Item form.
Note: There are templates and instantiated projects in Polarion where Workflow Signatures are already set as mandatory in the workflow configuration.
The Work Item form of those templates and projects already includes the "Workflow Signatures" section and no further "Form Layout" configuration is required.
To add the new "Workflow Signatures" section to the "Form Layout" configuration so that it appears in the Work Item form:
1. Project Administration > Work Items > Form Configuration.(On either the Project or Global levels.)
2. Click "Edit" beside "Default" in the "Form Layouts" section to add it to all Work Items. (Or "Edit" beside each Work Item type you'd to like to add it to.)
3. Paste in the "Form Layout Configuration" xml where you'd like the section to appear.
4. Click "Save".
* Active Load Balancing (ALB) for cluster installations has been introduced in this version. It comes with several
new optional configuration parameters. The feature can be switched on by setting the following new parameter to "true" in the polarion.properties file:
com.siemens.polarion.cluster.activeLoadBalancingEnabled=true
There are additional parameters that solve specific network configuration issues.
Check the Polarion_Enterprise_Setup_Guide.pdf available in the Polarion section of Siemens Doc Center https://polarion.plm.automation.siemens.com/documentation/latest for details.
* The following two properties were introduced and are enabled by default to prevent long running transactions.
(Only "read-only" user requests are affected. Requests with write operations are not.)
com.siemens.polarion.platform.threadKillingMode=killAll
com.siemens.polarion.platform.threadKillingTimeout=590000
TIP: Set the threadKillingTimeout property with a time that's less than the Apache ProxyPass timeout value configured in the polarion.conf or polarion-cluster.conf files.
See the following section in Polarion's Help for more information:
Administrator's Guide > System Maintenance > Topics > Prevent Long Running Transactions from Clogging up the Server
============
Version 18.1
============
* Administrators can now adjust the Repository Polling timeout value, for when changes are pulled from an external Git
repository, by adjusting the following property in the polarion.properties file:
com.siemens.polarion.repository.git.timeout=30000
(The default 30000 value is in milliseconds).
* The default configuration of the Test Execution Form contained a defect in several project templates.
It caused the background color to be omitted from the Test Status banner in Edge and Internet Explorer 11.
The problem is now fixed in the templates, but a manual update is needed in projects already created from them.
(See below for details.)
Affected project templates:
Agile Software Project,
Drive Pilot,
Drive Pilot QA,
E-Library,
V-Model Project,
V-Model Project QA.
To fix this problem in projects already created from these templates, open the administration page of the execution form in the target project
(Administration / Testing / Test Execution Form), and replace the following lines:
#set($statusColor = "#FFFFFF")
#set($statusColor = $testRecord.fields().result().get().fields().color().get())