5. Configuring Work Items

Customizing Work Items & Related Features

Work Items are a major focal point of data and activity managed by Polarion. There is of course no single definition or configuration of Work Items that would be applicable to all needs everywhere, so Polarion provides extensive possibilities to customize Work Items and functionality related to Work Items. This chapter covers these capabilities.

The Work Items topic of the Administration interface provides access to all Work Item related configurations. The following sections describe the various Work Item configurations and settings. In online Help, use the Contents panel to navigate to specific topics.

Configuring Work Item Types

Work Items represent various artifacts - requirements, tasks, change requests, for example. Each artifact type is represented in Polarion by a Work Item type defined in the global configuration, the project configuration, or both. (For projects, the default types are usually pre-defined in the project template on which the project is based.) If the default types do not meet your specific needs in terms of semantics or artifacts represented, you can customize the relevant configuration.

For example, suppose one default type for a project is "Defect", but your internal terminology is "Issue". You can change the name of the existing type to conform to your standard. Or suppose a given project needs to track an artifact "Supplier Part" but the project configuration has no analogous Work Item type. You can easily define a new type to represent such an artifact. If the need for the customized type(s) will extend beyond a single project, it is advisable to create or customize a project template and define the desired type(s) there. (For information see the Administrator's Guide topic Customizing Project Templates.)

You can customize the Work Item type configuration in the Types page of the Work Items Topic of Administration.

To configure Work Item types:

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

  3. Enter Administration, expand Work Items and select Type.

The configuration is stored in the underlying configuration file workitem-type-enum.xml. The Types page provides a visual interface for the configuration. On the page you can:

  • Modify properties of existing Work Item types.

  • Delete existing Work Item types.

  • Define new Work Item types.

    For new custom types, you can upload custom icon images. You can also specify an existing Work Item as a template for all new items of your new type. For more information see Defining Template Work Items.

The workitem-type-enum.xml file is one of a number of "enumeration" configurations. It is therefore alternatively accessible via the Enumerations page (Administration > Work Items > Enumerations: workitem-type-enum.xml). You need to access the file through this path if you want to remove an existing Work Item type configuration. For more information see Configuring Enumerations.

Configuring Time Points

A Time Point is essentially a named milestone that has a date when it occurs. 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. Time Points also appear in the project Live Plan (in products which have the feature) so that managers and others can see what items are planned to each one.

Time Points can be configured globally for the Repository, for project groups, and individual projects.

Creating a New Time Point

To create a new Time Point:

  1. Log in with administrative rights for the scope you want to configure.

  2. Enter the Administration interface.

  3. Open the project or repository in which you want to configure Time Points. (See User Guide: Accessing 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 the Create New Time Point button. A form appears in which you can specify the properties of the new Time Point.

  6. Fill in the properties of the new Time Point and click the Create button to create it.

Note about Time Point IDs

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 ("parent"), and configure a Time Point with the same ID but a different date in a project in that same group ("child"). The Time Points in the project would then override those defined in the project group. However, this is not recommended practice.

Note that if a parent Time Point is removed, or a child Time Point is created, it is necessary to clear the system caches.

Editing an Existing Time Point

You may wish to edit the properties of an existing Time Point, to extend the time or mark the Time Point closed, for example.

To edit an existing Time Point:

  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.

  2. In the Time Point detail pane, change any field in place (except ID) or click the Edit button to put all fields into Edit mode.

  3. Click the Save button to save your changes.

Deleting a Time Point

You can only delete a Time Point if no Work Items are associated with it in their Time Point field.

A button labeled Delete button 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 execute 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.

Configuring Prioritization

Several things relating to the prioritization of Work Items can be customized from the system defaults. These include:

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. The value is used by the LivePlan engine along with other factors to calculate where Work Items fall in the project plan.

Polarion's default configuration provides priority "ranks", which are simply textual labels representing a priority range. The default values are:

  • Highest (minimum value 90)

  • High (minimum value 70)

  • Medium (minimum value 50)

  • Low (minimum value 30)

  • Lowest (minimum value 10)

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 re-prioritize 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 panel, by drag-and-drop, and the item ends up 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.)

Examples: prioritizationModeIncrement=5 or prioritizationModeIncrement=20

Configuring Categories

By default, Work Items have a field called Categories. By assigning a Work Item to one or more Categories, you add yet another parameter for queries, reporting, and dashboards.

Categories are purely arbitrary- you can define any scheme that's appropriate to your needs. For example, your might define a User Interface or Look & Feelcategory for all Work Items that relate to your application's user interface. You would then be able to query for this Category, and dashboards will be able to report information such as unresolved items for the Category.

In order for Work Items to be assigned to Categories, you must first define Categories. This configuration is available only in the Project scope, as Categories only apply to individual projects and not to all projects globally.

Creating a New Category

To create a new Category:

  1. Log in with administrative rights for the Project you want to configure.

  2. Enter the Administration interface.

  3. Open the project or repository you want to configure. (See User Guide: Accessing Projects.)

  4. In the Navigation pane, expand the Work Items node and select Categories. (Note that this item only appears when working in a project.

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

  5. In the Content Pane toolbar, click the Create New Category button. A form appears in which you can specify the properties of the new Category.

  6. Fill in the properties of the new Category and click the Create button to create it.

Editing an Existing Category

You may wish to edit the properties of an existing Category, to expand the description or make the name more descriptive, for example.

To edit an existing Time Point:

  1. Navigate to the Project and select the Category in the Categories table as described in Creating a New Category.

  2. In the Category's detail pane, click the Edit button. The data in the Detail pane becomes editable.

  3. Change the properties as desired. (You can edit all except ID.)

  4. Click the Save button to save your changes.

Deleting a Category

You can only delete a Category if no Work Items are associated with it in their Categories field.

A button labeled Delete button appears beside the Edit button described above. If any Work Items are associated with the Category, the Delete button is disabled and you cannot delete the Category.

If there were ever actually a reason to delete a Category after Work Items are associated (and this should happen very rarely if ever), you would need to execute a query to locate all the affected Work Items, and then use Bulk Edit to remove the particular Category from all of them. You could then return to the Administration interface, select the Category as has already been described, and delete it by clicking the Delete button which should then be enabled.

Configuring Custom Fields

In addition to the default Work Item fields, you can configure custom fields of different types. For information on supported field types see Polarion Reference: Administration Reference: 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... a Defect or Change Request for example.

If you are not familiar with the basics of the different scopes, you may want to review Administration Basics: 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 custom-fields.xml. 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.

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 Configuring Enumerations and especially the section Creating Enumerations for Custom Fields.

Important

Multi-value custom fields must be of the enum type.

Understanding the different configuration files

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:

  1. All Work Item types, global scope

  2. All Work Item types, project scope

  3. Specific Work Item type, global scope

  4. Specific Work Item type, project scope

All Work Item Types - Global Scope

You need to work with the custom-fields.xml file in global Administration.

To access the custom-fields.xml configuration file:

  1. Log in with global (repository) administrator permissions.

  2. Enter Administration if your are not there after login.

  3. Select Repository in the Open Project or Project Group dialog (see User Guide: Accessing Projects).

  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 check Multi.

    Check Required if the new custom field should be mandatory. (End users cannot save Work Items until all required fields are filled.)

  7. To create additional custom fields, click the icon in the Actions column of the Custom Fields Designer.

  8. Click the Save button to save the custom field definition(s) to the global configuration file.

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.

All Work Item Types - Project Scope

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 will apply only to the specific project. This configuration 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:

  1. Log in with administrator permissions for the Project you want to configure.

  2. Click Administration in the tool view of Navigation.

  3. Open the project you want to configure.

  4. In the Navigation panel, expand Work Items and select Custom Fields.

    A 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 will say Global configuration and the Actions column will be empty, or the Type column will say Project configuration and the Actions column will contain links Edit (leading to a project-specific configuration) 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, let us assume there is no project-specific configuration for custom-fields.xml.

  5. Click the Create New Configuration button. The Create New Custom Field dialog 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 check Multi.

    Check Required if the new custom field should be mandatory. (End users cannot save Work Items until all required fields are filled.)

  8. To create additional custom fields, click the icon in the Actions column of the Custom Fields Designer.

  9. Click the Save button to save the new custom field definition(s).

Specific Work Item Type - Global Scope

In the global scope, you can configure custom fields that apply to a single Work Item type. As mentioned previously in this chapter, 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:

  1. Log in with administrator permissions for the repository.

  2. Click Administration in the tool view of Navigation.

  3. Select Repository in the Open Project or Project Group dialog (see User Guide: Accessing Projects).

  4. In the Navigation pane, expand Work Items and select Custom Fields. The Custom Fields administration page displays a table that lists all existing custom field configurations.

    In a new Polarion installation, there will be no Work Item type-specific custom field definitions in the global/repository configuration.

  5. Click on the Create new configuration button. The Create New Custom Field dialog appears.

  6. In the Work Item Type list, choose the Work Item type for which to create new custom field(s), and click Next.

    The Custom Fields Designer appears. You are now creating a global custom field for the Work Item type you selected in the dialog. The header of the table of custom field definitions displays a file name like [WORK-ITEM-TYPE-ID]-custom-fields.xml (where [WORK-ITEM-TYPE-ID] is the ID of the Work Item type you selected in the dialog... defect-custom-fields.xml, for example).

  7. Fill in the properties of the custom field you want to create. For the Fixed in Build example, enter an ID like fixinbuild, and Fixed in Build in the Name column.

    If you want to create a multi-value field, select Enum: in the Type column, and check Multi.

    Check Required if the new custom field should be mandatory. (End users cannot save Work Items until all required fields are filled.)

  8. To create additional custom fields, click the icon in the Actions column of the Custom Fields Designer.

  9. Click the Save button to create the new custom field definition(s).

Specific Work Item Type - Project Scope

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 will probably have some pre-configured custom field definitions for the Work Item types configured for the project in the template. You may find that you need to modify an existing custom field(s) configuration for some Work Item type rather than create a new one.

Rich-text Custom Fields

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 form as a multi-line text field with a toolbar enabling rich-text formatting of the field content (in exactly the same way as 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.

Figure 5.1. Rich Text Custom Field

Rich Text Custom Field

Result for end user of rich-text custom field configuration

If the Work Item being editing is one that is stored in a Document, the Table button is disabled in the rich text custom field toolbar and the user cannot insert any tables in the rich text field.

When working in the Multi Edit view in the Work Items topic, users can show the editor for rich text custom under the editor for the description field by clicking the Edit in the Work Item's row in the display.

Custom Fields with Dependent Enumerations

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:

  1. Configure enumerations and map value dependency between them.

  2. Configure custom fields of the enumeration types and map the selection dependency between them.

Configuring Dependent Enumerations

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.

  1. Open the Work Items > Enumerations topic of Administration.

  2. Define 2 enumerations and populate them with the desired values, remembering that the value selection in one is to filter the display of values from the other,

    Figure 5.2. Dependent Enumerations

    Dependent Enumerations

    Value selection in "parent/main" filters values in "dependent"

  3. Map the dependency between the enumerations. Open either of the enumerations in the editor, and use one of the 2 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, 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 should be listed for the selected value. For example, if Linux is selected on the left, you would select Ubuntu, SuSE and CentOS on the right, as they are all valid values for Linux. Leave other values unchecked.

    Figure 5.3. Mapping a Dependent Enumeration

    Mapping a Dependent Enumeration

    Mapping values to show users in an enumerated list of OS versions

  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.

Creating Dependent Custom Fields

This section explains how to create custom fields that use the enumerations described in the previous section.

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

Figure 5.4. Mapping Dependent Custom Fields

Mapping Dependent Custom Fields

Results of the Configuration for End Users

Removing or Changing Custom Fields

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:

Search: All and containsIncompatibleCustomFields:true in Project

Configuring Enumerations

Enumerations are basically lists of options that can be selected and applied as a value to some field of a Work Item. Typically, enumeration values appear as choices in a drop-down list. Take for example the Status field. Defaults for this field are specified in the project template. Typical options for a workflow configuration might be:

  1. Open

  2. Accepted

  3. In Progress

  4. Reopened

  5. Resolved

  6. Closed

Enumeration Files and Conventions

Enumeration values for are defined in XML files pertaining to specific Work Item fields. 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 define custom fields of the enumeration type, you would create an enumeration configuration file named similarly: [fieldID]-enum.xml where [fieldID] is the ID of the custom field. If you have a custom enumeration field named "Coffee" whose ID is "coffee", the enumeration configuration file would be coffee-enum.xml.

TIP

The default enumeration configuration files for the Repository scope are listed in the Administration Reference: Default Enumeration Configuration Files

In either scope, enumerations apply to all Work Item types by default. However, enumerations can be defined to apply only to a single Work Item type - a Requirement, Task, or Defect for example. Suppose you have a set of values defined for Severity. By default, the values specified in severity-enum.xml are used for all Work Item types. Now, suppose you want a different set of values for Defects. To override the configuration for all types and have different values just for Defect type items, you would need to create a type-specific configuration for Defect. The file would be named defect-severity-enum.xml where defect is the ID of the configured Work Item type "Defect".

Editing Options for Enumerations

There are 2 options for editing enumeration configuration files:

  • Online in the portal graphical interface

  • Offline, editing locally in an XML editor. (Advanced)

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 advanced administrators who have knowledge of XML and the XML schema involved.

Overview of the Configuration Process

The configuration process is essentially the same for both global and project scopes. Just remember that projects inherit the global configuration, so it's usually a good practice to configure the global defaults before customizing any projects. The process is essentially as follows:

  1. Log in with administrator permissions for the scope you want to work with.

  2. Open the repository or project you want to configure, enter the Administration interface (click Administration in the tool view of Navigation, and select Work Items > Enumerations in Navigation (topics view).

The Enumerations page presents a table of the existing enumerations configurations for the current repository or project. On this page you can do the following:

  • View the underlying XML code of any configuration file (click on the file name).

  • Create a new enumeration applicable to all Work Item types or to a specific type (click the Create new configuration button at the bottom of the page).

  • Modify an existing enumeration configuration (click the Edit link in the Actions column of the enumeration you want to change).

  • Remove an existing enumeration configuration (click the Remove link in the Actions column of the enumeration you want to remove).

Common Configuration Scenarios

This section covers several common enumeration configuration scenarios:

Editing an existing global enumeration

Your Polarion installation has global default configurations predefined for the following Work Item fields:

  • Hyperlink Role

  • Priority

  • Resolution

  • Resolution

  • Severity

  • Status

  • Linked Work Item Role

  • Work Item Type

  • Work Record Type

These enumerations apply to all Work Item Types. By default, there are no type-specific enumerations defined in the global scope. You can create type-specific configurations once you have the global defaults defined as you want them. You should review the default definitions for each global enumeration and make any changes before creating type-specific enumerations that override any of them. Always keep scope in mind. The global enumeration definitions will be the default for all subsequent new projects.

To edit an existing global enumeration:

  1. Make sure you are working in the global (Repository) scope.

  2. In the Enumerations table, find the row for the enumeration you want to edit and click the Edit link in the Actions column. The graphical enumerations editor appears, with the name of the configuration file in the header.

  3. The editor presents a table, each row of which represents a value that appears in the pick-list for the relevant enumeration type Work Item field. Change any existing values on any row, or delete any rows with values you don't want, or add rows for additional values you need. Note that the Default column enables you to specify a value as the default selection in the pick-list.

  4. Click the Save button to save changes to the underlying XML configuration file and return to the Enumerations page.

Creating a new type-specific enumeration

In either scope (global or project) you can create enumerations that apply to only one Work Item type. Before doing this, you should configure the enumeration that defines Work Item types (workitem-type-enum.xml in the scope for which you want to configure type-specific enumerations.

To configure an enumeration for a specific Work Item type:

  1. Be sure you are working in the scope you want to configure (Repository or project).

  2. On the Enumerations page (Administration > Work Items > Enumerations), click the Create new configuration button (bottom of the page). The Create New Enumeration dialog appears.

  3. In the Work Item Type list, select the type to which this new enumeration will apply (Requirement or Defect, for example).

  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 a new enumeration for the Work Item type you are configuring.

  5. Edit the enumeration definition in the enumeration editor, adding, removing, or changing values on the various table rows as desired, and click the Save button to create a new project-scope configuration file in the repository with the values you defined.

As mentioned earlier, projects inherit the globally defined enumerations. Project administrators can override the global enumeration configuration in the project scope in any or all of the following ways:

  • Modify inherited global enumerations. For example, the global link roles might not be suitable for the project, so the values could be modified in workitem-link-role-enum.xml in the project scope.

  • Create type-specific enumerations for the project. For example, the global settings might be oriented toward development projects, and in a requirements project, the values in the global enumerations for such things as Status, Resolution, or Severity might not be suitable, so a type-specific enumeration just for Requirement type Work Items might be created for the project.

  • Remove enumerations. For example, the global configuration might define enumerations for Test Case type Work Items, but the project doesn't use this type of Work Item, so a type-specific enumeration might be removed for the project.

Overriding global enumerations in a project

As mentioned earlier, projects inherit the globally defined enumerations. Project administrators can override the global enumeration configuration in the project scope in any or all of the following ways:

  • Modify inherited global enumerations. For example, the global link roles might not be suitable for the project, so the values could be modified in workitem-link-role-enum.xml in the project scope.

    In the Enumerations administration page for a project, any enumeration inherited from the global configuration shows Global Configuration in the Scope column. If no project-scope enumeration exists, there is a row for it in the table and the Create link appears in the Actions column. Clicking that link launches the graphical enumeration editor where you can specify the enumeration values for the project scope. The editor contains rows with values from the global configuration. You can modify these values, remove them, or add rows for new values.

  • Create type-specific enumerations for the project. For example, the global settings might be oriented toward development projects, and in a requirements project, the values in the global enumerations for such things as Status, Resolution, or Severity might not be suitable, so a type-specific enumeration just for Requirement type Work Items might be created for the project.

    To create a type-specific enumeration, use the Create new configuration button at the bottom of the Enumerations administration page. The Create New Enumeration dialog enables you to select a Work Item type and apply an existing enumeration to it, or create a custom enumeration for it.

  • Remove enumerations. For example, the global configuration might define enumerations for Test Case type Work Items, but the project doesn't use that type, so the inherited type-specific enumeration might be removed for the project.

Creating enumerations for Custom Fields

Custom fields can be of the enumeration type. If so, they must have pick-list values defined in an enumeration. Custom enumeration fields can use any existing enumeration. In fact the enumeration must be defined before a field can use it.

To create an enumeration for a custom field:

  1. Be sure you are working in the correct scope (Repository or project) for the configuration.

  2. Create a new enumeration using the Create new configuration button.

  3. In the Create New Enumeration dialog, 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 appears with an empty row, ready to add values to the new enumeration.

  5. Create the enumeration values and click Save. You now have the enumeration defined and ready for your custom field to use.

  6. Navigate to Work Items > Custom Fields.

  7. In the Custom Fields page, click the Edit link on the row of the custom field definition file that contains, or will contain the custom field. The Custom Fields Designer appears.

  8. If the custom field does not yet exist, define it in the last row of the table. In the  Type list, choose Enum:. Another drop-down list appears containing the IDs of existing enumerations. Choose the custom enumeration you created.

    Alternatively, you could change the Type of any existing custom field to the Enum: type and specify your custom field enumeration. You should only do this in the initial stages before any Work Items are created. You should not change the field type to Enum: when there are existing Work Items in the project with field values of a different type.

Using Custom Icons in Enumerations

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 to Widgets_myIcon1.png and upload the renamed file.

To upload a new custom image in an enumeration:

  1. Access the Enumeration Designer for the enumeration in the scope you want to configure.

  2. In the row for the value you want to have a custom icon, click the Select button in the Icon column. The Select Icon dialog appears.

    Figure 5.5. Custom Icons

    Custom Icons

    Upload local image files for use in configurations

  3. Click the Choose File button and select the desired icon image on your local disk. The name of the selected file now appears in the dialog.

  4. Click the Upload Repository Icon or Upload Project Icon button (depending on the scope you are working in), and wait for the icon image to upload to the portal. The image appears in the scope-specific icon set.

  5. In the icon set where the new icon image displays, click on the icon image. The dialog closes and the selected icon appears in the Icon column of the Enumeration Editor.

Hiding Obsolete Values

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 check the Hidden column on the value's row in the configuration page. When this column is checked, 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.

Common Enumeration Configurations

This section highlights enumerations that are frequently customized.

Work Item Types

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 "Supply Chain Risk" with whatever attributes you need for it to have.

This enumeration is so frequently customized that Polarion's Administration provides a special Navigation topic to access it: Work Items > Types. (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, 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.

For information, see the Administrator's Guide topic: Configuring 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 the Administrator's Guide topic: Custom Fields with Dependent Enumerations.

Query Enumerations in a Database

See the Advanced Administration section to populate an enum table so that it can be used with an external reporting tool.

Configuring Bulk Edit

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

Defining Template Work Items

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:

  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.

To create a template Work Item:

  1. Log into a project with administrator permissions.

  2. In Navigation, select Work Items to load the Table view of Work Items.

  3. Create a new Work Item of the type for which you want to create a template. For example, create a new Defect item to be the template for all new Defect items.

  4. Enter a title such as "DEFECT TEMPLATE".

  5. In the Description field, enter any boilerplate text you want users to see when the create a new item of this type. For example, the Description field might contain instructions on what information must be entered in the Description. (The boilerplate text will appear in the Description field of new Defect items created by users, and users will be able to replace it with their own text.)

  6. Set default values for other fields if desired. Keep in mind that default value for Status is set by the workflow, and Severity can be defined in the Severity enumeration in the project configuration. Your focus here is most likely to be on any custom fields for which a default should be set for new items of the type.

  7. Save the new item. Make a note of the new item's ID, as you will need it in the next process step, which is to specify the ID of the template item in the Work Item type configuration.

To specify the template item in the Work Item type configuration:

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

  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.

Field Values Not Copied

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

  • attachments

  • author

  • categories

  • comments

  • created

  • hyperlinks

  • linkedWorkItems

  • resolution

  • resolvedOn

  • status

  • title

  • votes

  • watches

  • workRecords

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.

Customizing Export Templates

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. (Note that a Repository-scope Export Template cannot be deleted from the project-scope Administration.)

To access Export Templates administration:

  1. Log in with administrator permissions for the scope you want to access. If your login does not automatically take you into Administration, enter Administration using the link in the tools view of Navigation.

  2. Open a repository (to access global repository templates) or a project.

  3. In Navigation, expand Work Items and select Export Templates.

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.

To customize an existing Export Template:

  1. Select the template in the Export Templates page.

  2. In the page toolbar, click Download, and save the template file to your local file system.

  3. Edit the downloaded Export Template file in a compatible application and save the changes. For example, if it is a template for Microsoft Word documents, edit the downloaded template in Microsoft Word.

    If you want to create a custom copy of the template in Polarion, save the modified file with a different name.

  4. Return to the Export Templates page in Polarion, click Upload, select the locally modified Export Template file, and upload it to the portal.

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

For additional information, see the Administrator's Guide topics Advanced Administration: Customizing XML Export Templates and Advanced Administration: Customizing XML Export Templates : Customizing Excel Export Templates.

Customize Field Filters

Administrators can customize which Plans appear in the Planned In list using a velocity script.

They can create custom queries with the following variables:

  • $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.

To add a custom field filter velocity script:

  1. Log in with administrator permissions and enter Administration.

  2. In Navigation, select Work ItemsField Filtering

  3. Enter a script in the Filtering Script column of the Filter section.

    (See the example scripts below.)

  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:

((project.id:elibrary AND NOT HAS_VALUE:projectSpan) OR projectSpan:(elibrary)) AND (allowedTypes:userstory OR allowedTypes:######NULL) AND NOT HAS_VALUE:finishedOn

This basic condition is always applied.

Any additional query that’s added, is appended to it.

Examples:

Only select Plans with an Open status.

status:open

If the Work Item status is Draft, only Plans defined as Iterations with an Open status will be shown.

If the Work Item has a status other than Draft, then all unfinished Plans defined as Iterations will be shown.

template.id:iteration AND
#if ($wi.getStatus().id == "draft")
status:open
#else
NOT HAS_VALUE: finishedOn
#end

Will only allow the selection of Plans defined as Iterations with a status other than Done, as long as the Work Items are assigned to the current user. Otherwise no Plans will appear in the list.

#if ( $wi.getAssignees().contains($user) )
template.id:iteration AND (NOT status:done)
#else
NOT status:(open inprogress done)
#end

Configuring Calculated Fields

You can define fields which derive their value from a calculation based on values of other fields in the same Work Item, or in child Work Items. Here are several key concepts to keep in mind:

  • 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 topic Work Items > Enumerations).

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

  • Calculated field values are calculated asynchronously and incrementally after each commit.

  • Values of calculated fields are not committed to the underlying repository, and are therefore not present in the Work Item history.

  • Calculated fields appear as read-only fields in the portal user interface. I.e., they are not modifiable by end users.

  • Calculated fields can be configured in these scopes: global, project and Work Item type.

The following operations are available for calculated fields:

  • sum: Calculates and renders the sum of two or more values.

  • multiply: Multiplies several values and renders the resulting value. Risk value * User Story size value, for example.

  • average: Computes the average of several values and renders the resulting value. Calculate average time spent on Work Items, for example.

  • min: Computes a minimum value. For example, compute the minimum time of several builds.

  • max: Computes a maximum value. for example, compute the maximum duration of a test execution.

Example Use Case: Work Item Cost

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 Cost configured for Task type Work Items, and a Total Cost field configured for Requirement type Work Items. The Requirements would be linked to the tasks that implement them with a "parent" link role (appropriately defined in the project link roles configuration). Alternatively, this could be done with just Tasks. Both custom fields could be configured for Task type items, and the tasks linked so that sub-tasks are children of a main task. The aggregated cost of the sub-tasks 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:

  • Check that role parent 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 type required for the <sum> calculation.

  • Configure calculated fields that reference the custom fields.

Defining the Custom Fields

For this use case, you would need to configure 2 custom fields (probably in the project scope). In the Work Items > Custom Fields topic, you would enter the following using the Custom Fields Designer:

  • ID: cost

  • Name: Cost

  • Type: float

  • Description: Cost of a Task

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

Defining the Calculated Fields

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:

  1. In Navigation, select Work Items > Calculated Fields.

  2. On the Calculated Fields page, click the Create New Calculated Fields button. The Create New Calculated Fields dialog appears.

  3. In the dialog, select the Work Item type from the list of types and click OK. (For the example being discussed here, you would select Task). The Calculated Fields Configuration page loads.

  4. In the Calculated Field ID column, enter the ID of field that will store the calculation result. In the example this would be the totalCost custom field.

  5. In the Source Field IDs column, enter the ID(s) of the field(s) to be calculated. In a sum calculation, this would be the ID(s) of the field(s) to be summed. In the example, it would be the cost field.

  6. In the Field From column, select the value specifying whether the field in Source Field ID(s) is a field in the parent or the child Work Item.

    If more than one field will be a source for calculation, you can add fields by clicking the icon next to the Field From value.

  7. To define another calculated field for the same Work Item type, click the icon in the Actions column and repeat the above steps to define another calculated field.

  8. Click the Save button to save changes and create the new calculated field(s).

The value of the calculated field totalCost for a Work Item will be a sum of the value of the cost field in that Work Item plus the sum of all values of the totalCost field from all child Work Items.

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

Modifying Calculated Fields

If you need to modify an existing calculated field configuration, you can do so. Be sure you are making changes in the right scope.

  1. In the Administration interface, select the scope of the configuration: Open Project or Project Group dialog. (See User Guide: Accessing 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.

Configuring Work Item Workflow

Note

This topic covers workflow configuration for Work Items. There is a separate workflow configuration for Documents.

Workflow controls a development process to ensure that no process steps are missed or skipped over. Workflows for Work Items in Polarion can be mapped to the steps in almost any process, whether it's defined by some methodology (Scrum, V-Model, etc.), completely by customer, or a hybrid of both.

Warning

Workflow definitions and status enumeration work in tandem.

"Type-specific" and "generic" enummerations 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:

  1. Open (which might be the initial status for new items)

  2. Accepted

  3. In Progress

  4. Resolved

  5. Closed

  6. Reopened

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

  1. Project-specific and Work Item type-specific

  2. Global and Work Item type-specific

  3. Project-specific

  4. Global

Configuration Process Summary

Generally you will perform the following operations in the order listed:

  1. Configure Work Item custom fields: define any that will be 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 (e.g. "Draft", "Implemented", etc.) 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 Work Item from one status to another throughout your development 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, a "Mark as Implemented" action might transition a Work Item to an "Implemented" status.

  4. Configure Functions and Conditions: This is optional, depending on whether or not any system functions should execute when an action is invoked by users, and if the execution should be conditional.

  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.

Accessing the Workflow Designer for Work Items

To access the Workflow Designer tool, you need to go into Administration for the scope you want to customize (global or project).

Access for Global Configurations

If you want to configure Global workflows, select Repository in the Open Project or Project Group dialog. Keep in mind that changes will apply not only to new projects, but to all existing projects unless a project-scope configuration has been defined for them individually.

Access for Project Configurations

To configure workflow for a specific project, select the project in the Open Project or Project Group dialog after entering Administration.

The Workflow Topic

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.

Figure 5.6. Table of Workflow Configurations

Table of 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.

Using the Workflow Designer

Please refer to the following figure while reading the information in this section.

Figure 5.7. Graphical Workflow Designer

Graphical Workflow Designer

Workflow Designer for a Work Item

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 drop-down list of actions. The Actions are defined in the Actions section of the designer, an they occur when the transition is triggered by the user changing the Work Item status. For more information, see Using the Transition Matrix.

The Statuses section is an enumeration editor for defining workflow status definitions for the scope in which you are working.

Below the Statuses section is the Actions section. 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 field types can be specified in these columns (i.e., not collection or structure types).

The Initial column in each Action row enables you to specify one action as the first action that must be executed 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 executed 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 is executed 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 display indicate if any workflow conditions and functions are configured for the action. (Indicator is a button labeled with the number of conditions or functions currently configured. Clicking the button opens the respective dialog where the conditions/functions are specified.)

The Actions column in this section of the designer contains 2 icons. The icon invokes the Action Details dialog, which provides tools for defining workflow functions and conditions to be executed when the Action is invoked.

Required roles

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 perform the Action. These roles may be either project or global user roles (e.g. "project_admin" or "admin") or two special roles:

  • workitem.assignee - only assignee of the Work Item has this role

  • workitem.author - only author of the Work Item has this role

Valid role names are all global and project roles (admin, user, etc.) 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 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.

Available conditions and functions

For a listing of the available conditions for this configuration and functions that can be specified, see Administration Reference: Workflow Conditions and Functions.

Action Names

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, suppose you have w statuses: Implemented and Verified, 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.

Using the Transitions Matrix

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

Consider an example of a workflow for a Requirement. Assume that, among others, the statuses Draft and Awaiting Review are defined.

Figure 5.8. Workflow Transition

Workflow Transition

Allow and disallow transition to take place between 2 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.

Figure 5.9. Multiple Transitions

Multiple Transitions

Where it makes sense for your process, enable more than one transition for a status

Workflow for Approvals

Polarion's standard project templates are pre-configured 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 Edit for 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 will be 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 the Administrator's Reference topic 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.

Requiring Signatures for Workflow Actions

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 check-box option, Requires Signature. Checking this option means that a user invoking the action is requested to provide an electronic signature, and the workflow transition will not 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 executes an approval or disapproval action, the password dialog 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 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 (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 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 (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.

Enabling Electronic Signatures Support

You can enable secure approvals via electronic signature to satisfy compliance or governance requirements. Use the following system properties in polarion.properties:

secure.approvals=true: Enables electronic signatures for approvals.

secure.approvals.comment=[COMMENT-TEXT]: The value in [COMMENT-TEXT] is used as the text of a new comment created when a user enters a password to confirm a secure approval. You can use the variable $user which will be expanded to the name of the currently logged-in user. The default value is: Default value is: Item was e-signed by $user.

secure.approvals.comment.onBehalfOf=[COMMENT-TEXT]: Similar to the above, except it supports one user confirming secure approval on behalf of another user. You can use variables $user (will be expanded to the name of the currently logged-in user) and $otheruser, which expands to the name of the user on whose behalf $user is approving. Default value is: Item was e-signed by $user on behalf of $otheruser.

Configuring Work Records

If your Polarion product 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.

Configuring Work Record Types

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 Administrator's Guide: Configuring Enumerations.

Making Type and Comment Fields Required

This configuration is available in both global (repository) scope and project scope. In both scopes, the fields are not required by default and you will need to create the necessary configuration to change this. Configuration is performed entirely in the Administration interface of the portal (i.e. you do not need to edit any XML configuration file).

To change the default and cause the Type and Comment fields of Work Records to be required fields:

  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, 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 this 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, check the Type Required box. To make the Comment field required in Work Records, check the Comment Required 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.

Locking Work Records

In Polarion products that support 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 "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.

To set a locking date for Work Records:

  1. Log in 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 (see User Guide: Accessing 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 will be the date when Work Records in the project will be locked.

  5. After changing the date, click the Save button to effect the change.

Enabling Decimal Hours in Work Records

By default, reporting of time values (e.g. Initial Estimate, Time Spent, etc.) 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 topic System Tuning for Advanced Administrators, property useDecimalHoursDurationFormat.

Configuring the Work Items Table

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 Administration Basics: 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 available in the Polarion web interface. Their changes are saved to their respective user profile. For information, see User Guide: Customizing the Work Items Table.

The Configuration File

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.

Accessing the Configuration Files

To access the table-settings.xml file:

  1. Log in with the necessary administrative permissions and enter the Administration interface.

  2. Open the scope you want to configure: Repository, or a project. (Click the current repository or project name in Navigation, just under the Polarion logo image.)

  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 as described in User Guide: Customizing the Work Items Table. To change the global configuration, be sure you have selected the Repository the Open Project or Project Group dialog before invoking the Table Configuration dialog.

Limiting Loading of Work Items

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 will always be 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 that the configured limit applies in Users, Roles, Projects, Time Points, Categories, Builds and Jobs in addition to the Table and Multi-Edit views in the Work Items topic.

Fields Displayed as Table Columns

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.

Table 5.1. Fields that can be displayed as Table view columns

Field IDShown by Default
type YES
title YES
priority YES
severity YES
status YES
created YES
assignee YES
author YES
plannedStart YES
timePoint Yes
description NO
categories NO
resolution NO
previousStatus NO
dueDate NO
initialEstimate NO
timeSpent NO
remainingEstimate NO
attachments NO
updated NO
plannedEnd NO
approvals NO
planningConstraints NO
linkedWorkItems NO
hyperlinks NO
linkedRevisions NO
comments NO

Note

Custom fields may also be used.

Configuring Queries

You can configure some named queries than can be entered in the Query field of the Work Items topic. Users can simply enter the query name and the associated query syntax will be executed.

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. The configuration is specified in the queries.xml configuration file. You will find comments with a customization example in this file.

To access the queries.xml configuration file:

  1. Log in with administrator permissions for the scope you want to configure (repository and/or Project).

  2. Enter the Administration interface.

  3. If making a global configuration, select Repository in the Open Project or Project Group dialog. If making a project configuration, navigate to and select the Project in the Open Project or Project Group dialog. (See User Guide: Accessing Projects)

  4. In the Navigation pane, expand the Work Items node and select Queries.

  5. You can edit the configuration file on line or download it for off-line editing and later re-upload. If you are editing a project for which no project-scope configuration exists, you can click the Paste global configuration button to load the XML from the global configuration into the online XML editor, where you can proceed to modify it.

  6. If you edit the file off-line, use the controls in the Upload New [Project][Global] Configuration section to upload the modified file back to the Polarion repository.

The default global configuration contains several pre-configured named queries, each contained in a <query> element. The user-friendly name is specified in the name attribute, and the Lucene query syntax, which will execute when the user invokes the name in the Query field, specified in the query attribute of the element. For example...

<query name="Unscheduled" query="NOT HAS_VALUE:timePoint.id"/>
                

...retrieves Work Items having no value specified in the Time Point field.

Changing the System Default Query

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.

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.

Configuring the Global Working Calendar

The Working Calendar feature enables the Polarion project planning engine to calculate 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 non-working 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 non-working time, such as national holidays, across the entire organization.

The user, or personal Working Calendar enables specification of vacations, personal holidays, and other personal time off from work, or fewer workdays or working hours in the case of part-time people, for individual users. This configuration can be performed either by an administrator, or by individual users.

The aggregate of both configuration scopes then affects the overall Live Plan of each Project. User calendars affect only the plan of projects for which they have a role. The Live Plan visually represents non-working time configured for both scopes and applicable to the project plan being rendered.

This section 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.

Accessing the Working Calendar

This section describes how to access the global Working Calendar, and a user's Working Calendar in the Administration interface. Administrator permissions are necessary for access. (Non-administrators wishing to edit their personal Working Calendar should consult the User Guide topic Configuring your Working Calendar.)

To access the global Working Calendar configuration:

  1. Enter the Administration interface.

  2. Select Repository in the Open Project or Project Group dialog.

  3. In the Navigation pane, expand the Work Items node and click on Working Calendar.

To access a user configuration:

  1. Enter the Administration interface.

  2. Select Repository in the Open Project or Project Group dialog.

  3. In the Navigation pane, expand the User Management node and click on Users.

  4. Use the Search feature to locate the user whose Working Calendar you want to configure.

  5. In the user account preview pane (bottom of the screen), scroll downwards, locate the Working Calendar button and click it to display the selected user's personal Working Calendar.

Modifying the Global Working Calendar

The Working Calendar page consists of the following 2 sections:

  • Regular Schedule

  • Schedule Exceptions

Regular Schedule

This section defines the "normal" work schedule for your organization. In a new installation, the defaults are set as follows:

  • Start Time: 09:00

  • End Time: 17:00

  • Days with working time specified: Monday - Friday

  • Days with NO working time configured: Saturday, Sunday

Days that have Start Time and End Time values are "Working" days. Days having no start/end time values are "Not-Working" days.

To change the start or end time for a Working day:

  1. Change the Start Time and/or End Time value(s) as desired.

  2. Click the Save button in the toolbar above the section.

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

NOTE: You can cancel changes by clicking the Revert button.

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, 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 2 types:

  • Time Off - the exception is time that will not be available for work in addition to any non-working 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.

To add a Schedule Exception:

  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 theActions column and repeat the above steps on the new row that appears.

  8. When you are finished defining your Schedule Exception(s), click the Save button in the Working Calendar toolbar. To cancel all changes, click the Revert button.

To remove a Schedule Exception:

  1. Click the in the Actions column of the exception you want to remove.

  2. Click the Save button in the Working Calendar toolbar. To cancel the remove (before any Save), click the Revert button.

Configuring Planning

You can configure certain defaults for the Live Plan project planning engine:

Note that the value for the number of hours per work day is read-only in this Administration page. This value is set in the system property polarion.durationHoursPerDay. See Administrator's Guide topic Advanced System Tuning for information on this property.

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.

To access the configuration:

  1. Log in with administrator permissions for the scope you want to configure (repository or project).

  2. Enter the Administration interface (click Administration in the tool view of Navigation).

  3. If making a global configuration, select Repository in the Open Project or Project Group dialog. If making a project configuration, navigate to and select the Project in the Open Project or Project Group dialog. (See User Guide: Accessing Projects.)

  4. In the Navigation pane, expand Work Items and select Planning. The Planning page loads in your browser.

  5. Set the field values as desired and click the Save button to save your changes. Refer to the Quick Help text on the page for information about the fields.

Splitting Work Items Across Time and Dependencies

There is a per-project option in the Planning configuration, Enable Work Item Splitting, that defines whether Work Items in a project can be split for project planning purposes. The option is enabled by default.

If enabled, then when Polarion searches for a space for a Work Item in the project plan, it may decide to split the Work Item into two or more pieces and thus make use of periods of time before the Work Item is fixed or postponed by a planning constraint. The resulting plan is more optimal in terms of priorities. This approach ensures that dependencies are handled.

The Live Plan visualization shows both split and nested Work Items.

Due Date Planning Option

The Enable Due Date Planning option controls the way in which the project planning engine processes and renders the due date of Work Items in the Live Plan. The option is disabled by default, and is available in the global scope only. Enabling the option has the following effect:

  • Due date will be considered a "suggestion" for planning, not "rule", meaning that it is considered by the planning engine when determining the order of items in the plan, but the produced plan can still violate the due date constraint -- which will always be indicated in the Live Plan visualization and Due Date column in the Table view of Work Items.

  • When determining a Work Item's best order based on due dates, any item that has a due date defined (including having a Time Point - see note below) will take precedence before any Work Item that does not have such date or time point defined. This implies that good practice is providing due dates (or time points) for all items when this option is turned on. Items without a due date are automatically penalized regardless of their priority.

  • Items without a due date specified will inherit the due date from their parent, if it can be determined. As such this makes an exception/correction to point 2 above. A due date defined at the child item always takes precedence, regardless of whether it is later or earlier than the parent due date.

Note

Wherever "due date" is mentioned, it means "time point or due date", as time points are internally interpreted as due dates. All items above apply for items from projects that have the Enable Due Date Planning option turned on.

Configuring Work Item Linking

There are 3 main configurations that affect the linking of Work Items:

  • Work Item Link Roles and Rules

  • Default state of the Suspect attribute of Work Items

  • External Linking

Link Roles and Rules

You can configure link roles that define the relationship between linked Work Items. For example, a link role depends on can be specified for a link between Work Items to indicate that the source item depends on the target item. When you define such a link role, you also define its opposite role. For example, the depends on link role could have an opposite of is depended on by. This link role will be seen by anyone accessing the target item.

Link roles can be configured globally for any repository, and for individual projects to override the global configuration. You can define as many link roles as you need for your process. Project templates may predefine project-scope link roles.

Each link role definition can have one or more rules. Rules control which type or types of Work Items can be linked to which other type or types with the selected role. For example, a link role verifies might have a rule that in effect says that the role can only be applied from a Test Case type Work Item to a Requirement type Work Item.

Important Tip

Defining rules for link roles is extremely important because they are reflected in the user interface elements in Work Items for creating links. Rules prevent users who may not understand the various link roles and the directionality of linking from creating inappropriate links which result in erroneous data in the system that is then reflected in dashboards and reports.

Accessing the Configuration

Link roles are an enumeration. The configuration settings are stored in the workitem-link-role-enum.xml configuration files. A graphical editor is provided for editing both link roles, and rules for each defined link role.

To access the link roles configuration:

  1. Log in to the portal with administrator permissions for the scope you want to configure.

  2. Enter the Administration interface (if not already there from a previous login)

  3. To configure the global scope,select Repository in the Open Project or Project Group dialog.

    To configure a project, select the project to configure in the same dialog.

    (See User Guide: Accessing Projects.)

  4. In the Navigation pane, expand Work Items and select Enumerations. The Enumerations page loads in the Content Pane.

  5. In the Enumerations table, locate the row with workitem-link-role-enum.xml in the Name column

  6. If configuring the Repository scope, click the Edit link in the Actions column.

    If configuring a project, what you click depends on whether or not a project configuration already exists.

    • If a project configuration does exist, the Edit link appears in the Actions column, and you should click it to access the Enumeration Designer.

    • If no project configuration exists, the Create link appears in the Actions column, and you should click that to access the Enumeration Designer.

Defining Link Roles

The Enumeration Designer presents 2 sections: one for the link role definitions (the top section) and one for rules. In the definitions section, you can:

  • Modify the properties of any existing link role.

  • Remove any existing link role (click the in the Actions column).

  • Add a new link role (click the icon in the Actions column

TIPS

  • ID, Name, and Opposite Name are required. Spaces are allowed.

  • Do not use spaces in the ID and limit characters to ASCII upper and lower case letters, and numbers, and underscore.

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

  • Default, if checked, will result in that link role appearing first in the list of of roles in the Linked Work Items section of the Work Item form. (If this remains unchecked for all roles, then the first role defined appears first in that list.)

Defining Rules

The Rules for link role section of the Enumeration Designer is where you define rules for the various link roles. Here you can:

  • Define new rules.

  • Modify existing rules.

  • Delete existing rules.

Important

New and modified rules are not applied to existing links between Work Items. If you have links that predate the rules feature, or which existed before rules were configured on your system, the system will not generate any errors if any of these links violate link role rules, and the system will still contain links which now violate rules.

To access the rules for a link role, click inside one of the fields in its row in the top section of the page. The row is highlighted and any existing rules appear in the rules section. Any new rules you define are applied to the selected link role. A single link role may have multiple rules.

A rule says, in essence, that a link with the selected role is allowed from one or more Work Item types to one or more Work Item types. Accordingly, each rule has a property From Types and To Types. Both are multi-valued, since a rules may affect multiple Work Item types. A rule may permit links from a single type to multiple types, from multiple types to a single type, from multiple types to multiple types, or from a single type to the same type only. (The Same Type check box can be used for the latter).

Figure 5.10. Link Role Rules

Link Role Rules

Example of rules for a derived from link role

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 e.g. a Requirement type is defined in the current project and a Test Case type is defined in a different project.

Configuring Work Item Linking 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 form in the Work Item Viewer/Editor pane in the Table view of the Work Items topic.

To access the configuration:

  1. Log in with administrator permissions for the scope you want to configure (repository or project).

  2. Open the repository or project you want to configure and enter the Administration interface if you are not already in it.

  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 Menus and Linking Menus, or update or delete existing configurations, if any.

When Creating a new configuration, you select the Interface in which the configured menu will appear, 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.

Rules in the Work Item interface

Link role rules control the items reflected in the Action menus in the Work Item form. Users creating links to other Work Items can only select valid link roles because, thanks to the rule definitions, only valid link roles are presented in the menus.

Figure 5.11. Link role rules reflected in the UI

Link role rules reflected in the UI

Users can only select a link role that is valid for the current Work Item

Linking with Opposite Role

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. Backlinks from the same project can be added or removed. 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 is used, it presets the correct query based on the current project's configuration.

When linking with the opposite role, there are some limitations:

  • Opposite link can only be created/editing in an individual Work Item (that is, not using Bulk Edit or Multi Edit).

  • Opposite links cannot be created in the Document Editor. User must open Document-contained items in the Table view of Work Items.

  • Backlinks from different projects cannot be edited.

Suspect Default State

You can configure the default state of the Suspect attribute of Work Items.

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.

To access the configuration option:

  1. Log in with administrative permissions for the scope you want to configure (repository and/or Project).

  2. Enter the Administration interface and open the repository or project you want to configure. (See User Guide: Accessing Projects.)

  3. In the Navigation pane, expand the Work Items node and select Linking. The Linking administration page appears.

  4. To have the suspect attribute automatically set to true for all new Work Items, check the Auto Suspect box. Clear the check box if it is checked and you do not want new Work Items to automatically have the Suspect attribute automatically set.

  5. Click the Save button to save your change.

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.

Enabling Linking Across Servers

In a clustered server environment with multiple Polarion servers, if any of the servers 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 User Guide: Linking Work Items: Linking to Remote Work Items.

Configuring Auto-assignment

You can configure Polarion to automatically assign new or existing Work Items to one or more users based on some condition(s). This 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 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 with some value of "usability" in the Category field is automatically assigned to some user in charge of 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.

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.

Accessing the Configuration

To access the Auto-assignment configuration:

  1. Log in with administrative rights for the scope you want to configure (repository or Project).

  2. Enter the Administration interface.

  3. If making a global configuration, select Repository in the Open Project or Project Group dialog. If making a project configuration, navigate to and select the Project in the Open Project or Project Group dialog.

    (See User Guide: Accessing 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.

Creating a New Rule

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

    The Auto-assignment Configuration page appears.

  • In the Conditions section, specify the conditions which must be met in order for Work Items to be automatically assigned. Refer to Quick Help embedded in the page.

  • In the Assignees section, specify one or more users to whom Work Items will be assigned which the conditions specified in Conditions.

  • Click the Save button. If you want to create or edit another rule, click the link Return to Auto-assignment.

Modifying an Existing Rule

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.

To modify an existing Auto-assignment rule:

  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.

Removing a Rule

To remove and existing Auto-assignment rule:

  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.

Important

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.

Configuring Voting

You can configure the Work Item Voting feature to enable or disable it (it is enabled by default) and/or set the per-user limit of votes on Work Items in projects.

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. The configuration is specified in the voting.xml configuration file. You will find comments in this file that explain the elements and their usage.

To access the voting.xml configuration file:

  1. Log in with administrative rights for the scope you want to configure (repository and/or Project).

  2. Enter the Administration interface.

  3. If making a global configuration, select Repository in the Open Project or Project Group dialog. If making a project configuration, navigate to and select the Project in the Open Project or Project Group dialog.

    (See User Guide: Accessing 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 the controls in the Upload New [Project] Configuration section to upload the modified file back to the Polarion repository.

Configuring Multi-language Support

An administrator can optionally 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 form in tracker views, and users can switch languages in Documents to view translated Work Items.

For information on this configuration, please see Administrator's Guide: Configuring the Portal: Configuring Languages.

See also: User Guide: Viewing Work Item Translations.