The "My Hats" feature of Polarion ALM provides a handy means for users to work with the platform in different contexts. For example, one user may at some times wear a "Manager" hat and at other times a "Developer" hat. Each "Hat" enables a customized view of the system, with just the topics needed, and with customized Work Item form layouts. By default there are 4 "Hats" pre-configured:
Default
Manager
Developer
Requirement Engineer
Each Hat configuration displays it's own set of topics (in the Topics portlet), and some have custom layouts defined for the Work Items form and for the form for the standard Work Item type "Defect". You can modify the default configuration for any of the pre-configured "Hats", and you can also create new custom "Hats".
Hats can be configured in the repository scope only (i.e. not per project). A default set of Hat configuration files is provided which you can use as the basis for customizations. Some of the demo projects that ship with Polarion ALM may also contain customized Hat configuration files which you can reuse. Keep in mind that although these exist in a demo projects' repository, they do not work when you are in such projects. They are provided as examples that you can reuse and/or modify for the global configuration.
To configure exiting or new Hats, you need administration rights for the repository. You will work in the Repository perspective to download configuration files to a local drive, create directories (for new Hats only), and upload modified XML configuration files. A good way to begin to understand how this configuration works is to take a look at the default Hats configuration.
The configuration for the My Hat feature is located in the .polarion/hats directory (under the repository root).
To access the configuration directory:
In the Projects portlet, click on Repository.
Enter the Repository perspective by clicking on the Repository perspective selector in the left-hand navigation zone. The Browser page for the repository appears in the Work Zone.
Note that you will need administration rights for the repository in order to perform My Hats configuration.
Locate the hats directory (folder) and click on the name to enter the hats directory.
The Info page for the directory lists several subdirectories. Each corresponds to an existing Hat configuration. The name of each subdirectory is the name of one of the "Hats" that appears in the My Hats list in the portal header. So for example, the developer directory appears as the Developer "hat" in the My Hats list.
Click on the _default directory name to enter that directory.
This directory contains the Default Hat configuration. The configuration files found under it can be used as models for any customizations you want to make to the My Hats feature.
Notice that the _default directory also contains two subdirectories. These contain the XML configuration files which control different aspects of the portal user interface when the specific Hat is selected by an end user in the UI. Every Hat configuration directory must contain at least one subdirectory with one of these names. The purpose of each subdirectory is as follows:
portal: contains a configuration file which controls the topics that display in the Topics portlet.
tracker: contains configuration files which control layout of Work Item forms.
Any of the Hat-specific configuration directories may optionally contain a file named hat.properties which defines the name of the Hat, and the icon of the Hat that appear in the My Hats combo box in the portal header when the end user selects the Hat defined by the directory containing the hat.properties file.
Presence of hat.properties in any Hat configuration directory is optional. If not present, defaults will be used automatically. Note that this configuration file should only be used in one of the Hat-specific configuration directories (e.g. developer, manager, requirementEngineer) - never in the _default directory. If used there, all Hats would have the same name and icon.
An example of this file is provided in the requirementEngineer folder in the default Polarion configuration. Refer to comments in the file for information about the properties and settings.
This directory must contain a file named topics.xml. This file contains elements which define the topics available in the Topic portlet when a user "puts on" the respective Hat. In the default configuration, all possible topics are present. By commenting out or removing the relevant elements, you can cause some topics not to appear when the Hat is applied by the user. Refer to comments in the _default/portal/topics.xml file.
The directory can also contain a perspectives.xml file, as you can see when looking at the _default configuration in a default Polarion installation. This file defines which perspective selectors are visible to the end user when the Hat defined by the parent directory is selected in the UI. When the perspectives.xml file is not present in a given Hat's configuration directory, all perspectives are visible unless the _default folder contains a perspectives.xml file, in which case the perspectives configured there apply to all Hat configurations whose directories do not contain a Hat-specific perspectives.xml file.
This directory (in the default configuration) contains these files:
form-filter.xml: defines how fields are filtered when a user activates Work Item filtering (one part of the My Hats feature).
form-filter.xsd: the schema for the form-filter.xml data.
form-layout.xml: defines the Work Item form layout when the respective Hat is invoked by the user.
form-layout.xsd: the schema for the form-layout.xml file.
topics-layout.xml: defines sub-topics (if any) for the topics which may appear when the Hat is invoked by the user.
The XML files are the ones you will mainly need for any configuration work.
Hats available to end users can be restricted by adding a configuration file name roles.xml to any Hat definition folder. The file format is same as /.polarion/security/roles.xml, but without the defaultHat attribute. If the roles.xml file is not present in a Hat definition folder, then the Hat is available to all user roles (for backward compatibility), except when the roles.xml file is placed in the _default folder, then the Hat-to-role configuration is applied to all Hat definitions which do not have their own roles.xml file.
The default Hat for any user role can be configured the Administration perspective (User Management - Roles topic). The Hat specified there is used if there is no previous selection to be remembered by the system, or the previously selected Hat is not available to the user in a new scope. The configuration is stored in .polarion/security/roles.xml (global configuration) or .polarion/security/project-roles.xml as the defaultHat attribute of a <role> node. Example:
<role defaultHat="developer">developer</role>
The Role form only allows selection of the Hats configured as available for the role being edited.
When a user has several roles in the current scope, then the first default Hat found is applied to the user interface. The user's roles are taken in the order they are configured in the .polarion/security/user-roles.xml file. When the scope is project, then the project-specific user roles are applied first, followed by the global user roles.
There are 2 basic configurations you can perform for the My Hats feature:
Modify the configuration files for an existing "Hat" to change what is available in the portal when the user "puts on" the Hat.
Create a new "Hat" configuration, using modified versions of the default configuration files committed to the necessary directory structure described in the previous section.
It is recommended that you download and review the configuration files in the subdirectories of the Repository/polarion/hats/_default directory which contain comments explaining the various elements. From these you should be able to perform most modifications.
As previously mentioned, you need administration rights for the repository.
The basic steps for this process are:
Download the configuration files from the Hat configuration you want to customize to a local or shared location.
Create a backup of the Hat configuration files you download so you can restore them in case of problems with the changed configuration.
Modify the Hat configuration files to show the desired name, icon, topics, and Work Item form layout for the Hat you are modifying.
Upload the modified configuration file(s) back to the correct Hat directories in the Repository.
To better understand what's involve in modifying an exiting configuration, read the next section on creating a new Hat configuration. The files and directories involved are the same, only to modify an existing configuration you need only modify existing files in an existing directory tree rather than creating a new structure and new copies of the configuration files.
Download the configuration files from the default Hat configuration to a local or shared location.
Create a backup of the default Hat configuration files you download so you can restore them in case of problems with the new configuration.
Modify the default Hat configuration files to show the desired name, icon, topics and form layouts for the Hat you are modifying.
Create the requisite directory structure, with an appropriate name, in the repository for new Hat configuration.
Upload the modified configuration file(s) back to the correct repository directory.
As previously mentioned, you need administration rights for the repository.
Let's suppose you want to create a new "Hat" for technical writers on your team. This section will walk you through the steps. You should first go the Repository perspective and download the default configuration files as described in the Process Overview section.
The first set of steps is to create the repository folder structure for the new Hat configuration.
To create the main folder for a new Doc writer Hat:
In the Projects portlet, select Repository.
Enter the Repository perspective. The Info page for the repository root appears, showing a table of the files and folders.
Click on the .polarion folder to navigate into it.
Click on the hats folder to navigate into it.
Click the Add Directory icon on the Info page toolbar. The Add Directory page appears.
In the Directory name field, enter doc_writer (or a suitable name for your own configuration - no spaces in the name!)
Note that if you do not specify a name for the hat in hat.properties, the directory name you specify here will appear to users in the My Hats combo box in the portal header.
Optionally update the Comment field and click the button. The Change confirmation page appears.
In the Change confirmation page, click . The new Hat folder now appears in the Info page for the hats folder.
Click on the new doc_writer folder to navigate into it.
Now that the main Hat configuration directory doc_writer exists, we need to create the subdirectories for the configuration files.
To create the requisite subdirectories:
You should now be in the doc_writer directory. Click the Add Directory icon on the Info page toolbar. The Add Directory page appears.
In the Directory name field, enter portal (all lower case).
Optionally update the Comment field and click the button. The Change confirmation page appears.
In the Change confirmation page, click . The portal directory now appears in the Info page for the doc_writer directory.
Repeat the above steps to create a directory named tracker (all lower case).
You have now completed the directory structure necessary for the new Doc_writer "Hat". You now need to modify the configuration files you downloaded, and afterwards upload them to the correct directories.
The Hat name that appears to users in the My Hats combo box is specified as an unquoted string value in the name of the hat.properties. This file should reside in the root directory of a Hat configuration. So in our example, it should exist in the doc_writer directory, which is the root of our hypothetical "Doc Writer" Hat configuration. So you would specify the name as follows:
name=Doc Writer
You will find comments in the hat.properties file of the Default configuration (REPOSITORY/.polarion/hats/_default that will guide you when actually performing the configuration.
The icon image that appears to users in the My Hats combo box is specified as an unquoted string (representing a system path to an image file) in the iconURL of the hat.properties described in the previous section. Several Hat image files are provided which you can use in custom Hat configurations:
hat_generic.gif
hat_green.gif
hat_blue.gif
hat_brown.gif
hat_magenta.gif
So to show a brown hat image in your custom Hat configuration, you would specify the iconURL as follows:
name=Doc Writer
iconURL=/polarion/ria/images/hats/hat_brown.gif
You can optionally use your own custom icon image. It must be in GIF format, and no larger than 20 x 20 pixels (recommended maximum).
To use your own custom GIF image in a Hat configuration:
Go to the file system of the computer running Polarion ALM and navigate to the installation root.
Copy your custom image file to:
POLARION ROOT\polarion\plugins\com.polarion.java2js.server_1.0.0\webapp\ria\images\hats
Return to the hat.properties file you are customizing and specify the file name of your custom image in iconUrl, keeping the path and just replacing the file name:
iconURL=/polarion/ria/images/hats/hat_myCustomHat.gif
You can define which topics appear in the Topics portlet when a user "puts on" the new Hat. For the Doc_writer example, let's say a person wearing the Doc Writer hat only needs to see the topics Work Items, Wiki, and Builds. The steps for this configuration would be:
Open the topics.xml file in a XML or text editor.
Comment out or remove elements in the <projects> element, leaving only the elements for the desired topics:
<topics>
<projects>
<topic id="workitems"/>
<topic id="wiki"/>
<topic id="builds"/>
</projects>
</topics>
Save the changes to the file.
Back in the Polarion ALM portal, navigate into the Repository/.polarion/hats/doc_writer/portal folder.
Click the Add file icon in the info page toolbar of the portal directory Info page. The Add file page appears.
Click the Browse button, select the modified topics.xml file on a local/shared drive.
Optionally add a comment and click to go to the Change confirmation page, where you click again to confirm the change.
When a "Hat" is "put on" by a user, the Hat can specify a custom layout for the Work Item form. This layout is specified in the form-layout.xml file which must reside in the tracker directory of the Hat configuration. In this file you can configure which field should appear when the end user "puts on" the configured Hat, and how these are laid out on the form.
The form-layout.xml for the "Default" Hat contains extensive comments on the various elements and how to structure them to achieve the desired layout. You can download this file from: Repository/.polarion/hats/_default/tracker/.
Any Hat can have filtering of the Work Item form configured for it. Filtering hides some fields, or sets some fields to read-only for different workflow actions and states. Filtering is engaged when a user invokes Show Minimal Fields on the Work Item form toolbar. It is not a mechanism for restricting access to fields. It merely puts less frequently needed fields and editing capability out of the user's way. Visibility and editing can be restored by the user any time.
Filtering is defined in the form-filter.xml file which must reside in the tracker directory of each Hat configuration. Filtering for actions are specified in a set of <action> elements contained within the <action> element. Filtering for states are specified in a set of <state> elements contained within the <states> element.
Consider the following examples from the Default hat configuration.
<action refId="_create" fieldNames="@required,description,linkedWorkItems" />
This specifies that when filtering is engaged by the user, when a new Work Item is created the Work Item form will show only required fields, the Description field, and the Linked Work Items field. If you wanted to customize this to include the Comments field, you could do so:
<action refId="_create" fieldNames="@required,description,comments,linkedWorkItems" />
For more information, you can refer to comments in the form-filter.xml for the "Default" Hat configuration (Repository/.polarion/hats/_default/tracker/form-filter.xml).