Configuring Interface Views

- see Views-related Features and Licenses for details.

You can configure different variants of the Polarion user interface for end users who work with the Polarion platform in different contexts. 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 presentation, displaying just the navigation topics, Work Item field content and Work Item form layout needed for the selected work context.

A default set of Interface Views is defined in the 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. The default Interface Views in the default Project Templates are pre-configured to provide just the information typically needed when working in the role described by the name.

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.

Important

Interface Views are not a security feature. For example, they will not prevent some users from accessing some information. User roles and permissions should be used to control users' access to portal content.

Configuration Scope

You can define Interface 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 customize Interface Views to change the display of navigation topics, Work Item fields, and the Work Item form layout. You can also create new Interface Views that specify the Navigation topics, Work Item fields and Work Item form layout to display when a user selects the View in Navigation. All configured Interface Views appear in the Views list in the Tools mode of the Navigation panel (below the Help link).

To see the interface Views currently configured for a project or change to a different View, click the Tool icon in Navigation, then with the panel in Tool mode, click the list next to the mask icon and select the desired View name. (The current View in highlighted in the list.)

You must have Administrator permissions for the scope you want to configure (Repository or Project).

Process Overview

The following Administration topics are needed to configure Interface Views:

  • 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 form (Form Filters), and the form layout to be used when a user is working in the Interface Views.

The main configuration process steps are:

  1. Create a new interface View in the desired scope, or access an existing interface View.

  2. Configure field filtering for the Work Items form to control what fields appear in the form when a user invokes the Interface View.

  3. Configure the layout of Work Items form 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.

Following sections in this topic provide more detail about each of these main steps.

It is important to note that when a new Work Item form filter or Work Item form layout configuration is created, its content is pre-filled with its parent configuration. The inheritance scheme is as follows:

  • From default to specific Interface View

  • From unspecific to specific Work Item type

  • From global to project scope

Views-related Features and Licenses

When at least one Polarion 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.

If no Polarion ALM license is present:

  • Form Configuration (layouts + filters), Read-only Fields, and 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.

Defining a New Interface View

To create a new Interface View:

  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 section of the page.

  4. Enter a unique ID for the new View. Use letters, numbers, underscore, but no spaces. For example: techWriter.

    The system will derive a value for Name from your input. This value will appear in the Interfaces 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 to be available only to users who have a specific role assigned them in User Management, 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 newly created a new Interface View does not differ from the default in terms of Navigation topics, Work Item fields shown, and Work Item form layout. It is necessary to address these configurations for the new View. They are covered later in this topic. See Configuring Work Item Form Filters, Configuring Work Item Form Layout, Defining Read-only Fields, and Controlling Navigation Topics.

Accessing an Existing View Definition

You may need to access an existing Interface View configuration to modify roles, or delete the definition.

To access an existing View configurations:

  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.

Deleting a View Definition

If you want to delete an Interface View definition, select it according to the steps in the previous section. When the desired View is selected, click the Delete button in the toolbar of the detail section of the administration page.

Configuring Work Item Form Filters

You can configure filtering of the Work Item form 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 button on the Work Items form's toolbar. Remember that this is not a mechanism for restricting access to fields. Users can restore visibility and editing of fields hidden by filtering at any time.

To configure Work Item form filtering:

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

Creating a New Filter

To create a new Work Items form filter:

  1. In the Form Filters section of the Form Configuration page, click the Create New Form Filter button. The Create New Form Filter dialog appears.

  2. In the dialog's View list, select the 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.

Modifying an Existing Filter

To modify an existing Work Items form filter:

  1. Navigate to the Work Items > Form Configuration topic as described earlier in this section. Be sure you are 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 the Save button when finished, or the Cancel button to undo unsaved changes.

Removing an Existing Filter

To remove an existing Work Item form filter:

  1. Navigate to the Work Items > Form Configuration topic as described earlier in this section. 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.

Note

Global configuration for the -- Default -- View plus the -- unspecific -- type cannot be deleted because other configurations are derived from it.

Configuring Work Item Form Layout

Note

If Polarion Requirements or Polarion QA is running on a server where no Polarion ALM license is present, then multiple Interface Views are not available, and only the form layout of the Default View is configurable.

For any Interface View, you can configure the layout of the fields on the Work Item form. This form 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.

This section explains how to access the configuration data and the online editor. You will find comments embedded in the XML code, plus embedded Quick Help on the editor page that provides information about the elements and attributes used in the configuration.

To access the form layout configuration:

  1. Open the project or repository for which you want to configure Work Items form layout, 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). This section enables you to create a new form layout, and presents a table of existing Views having a customized Work Item form layout. You can edit or remove any existing form layout.

Creating a New Form Layout

The Interface View for which you want to create a custom form layout must already exist. That is, you cannot create new View during the form layout configuration process.

To create a new form layout:

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

  3. In the View list, select the Interface View you want to configure. If you want the form layout 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).

  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.

Modifying an Existing Form Layout

To modify an existing form layout:

  1. Open the project or repository which contains the Interface View you want to modify.

  2. In the Navigation pane, select Work Items > Form Configuration.

  3. Locate the table of existing layouts in the Form Layouts section of the Form Configuration page (scroll down to see it if necessary). Click the Edit button on the row of the layout you wish to modify. The Form Layout Configuration page loads in your browser, and the XML code for the selected layout loads in the embedded XML editor.

  4. Modify the XML code as desired, referring to the page's Quick Help text if necessary. Click the Save button when finished.

Removing an Existing Layout

To remove an existing form layout:

  1. Navigate to the Work Items > Form Configuration topic as described earlier in this section. Be sure you are in the correct project or repository.

  2. In the Form Layouts section, find the layout you want to remove in the table.

  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 other configurations are derived from it.

Defining Read-only Fields

Unless configured as read-only, many fields can be edited "in place" without placing the entire Work Item form into Edit mode. In each Interface View configuration, you can define which fields should be read-only when the entire Work Item form is not in Edit mode. The configuration can include custom fields. You can perform this configuration for any Interface View in which you want specific fields to always 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, for example, a custom "Customer" View.

The same read-only restrictions provided by the configuration apply in the Multi Edit presentation of Work Items, and 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.

This configuration is available in both global (repository) and project scopes. Remember the project settings override the global settings, which are the default for new projects.

To configure read-only fields:

  1. Log in 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.

  4. To create a new configuration, click the Create New Read-only Fields button. The Create New Read-only Fields dialog appears.

  5. In the View list, select the Interface View in which you want a field to be read-only. If the configuration should apply to a specific Work Item type, select the type in the  Work Item Type list. Then click Next. The Read-only Fields Configuration page appears.

  6. In the Read-only Fields table, enter a status ID and one or more field IDs (comma-delimited) in the respective columns. Click the icon to add more rows to the table and configure additional statuses and fields. Refer to the Quick Help text on this page for reference information and links to values.

    Note that there are 2 constants defined for the Status ID field which can be specified instead of an actual status ID value:

    • _default: the fields specified in Fields will be read-only when no status-specific configuration exists

    • _create: the fields specified in Fields will be read-only when a new Work Item is in process of being created but is not yet saved.

    Note also that 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, i.e. writable fields, by specifying the desired fields prefixed with '-'. More information, command syntax, and an example are provided in the embedded Quick Help on the configuration page in Administration.

Controlling Navigation 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 and Documents and Pages topics in addition to the Home and project and user Shortcuts topics.

To configure Navigation 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, 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 <projects> element which correspond to the Navigation topics you do not want to show in the Interface, leaving only the elements for the desired topics. For example, your configuration for the previously mentioned Tech Writer View might be:

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <topics xmlns="http://polarion.com/schema/Portal/Topics" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://polarion.com/schema/Portal/Topics">
        <topic id="home"/>
        <topic id="wiki"/>
        <topic id="workitems"/>
        <topic id="project_shortcuts"/>
        <topic id="user_shortcuts"/>
    </topics>
                        

  5. Save the changes to the file.