Common configuration scenarios

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

• Hyperlink Role

• OSLC link role

• Priority

• Resolution

• Risk

• Severity

• Status

• Work Item Link 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.

Steps to edit an existing global Enumeration:

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

2. Open Work Items Enumerations.

3. 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 Enumeration editor page opens, with the name of the configuration file in the header.

4. The editor presents a table, each row of which represents a value that appears in the select-list for the relevant 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 do want. Note that the Default column enables you to specify one value as the default selection in the list control.

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

In either scope (global or project) you can create enumerations that apply to only one Work Item type. Before doing this, you must configure the Work Item types in the desired scope. This is most easily done in the Work Items Types topic of Administration. If you prefer, you can do the same configuration in workitem-type-enum.xml in the Enumerations topic.

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

2. On the Enumerations page (AdministrationWork Items Enumerations ), click Create new configuration at the bottom of the page. The Create New Enumeration dialog box appears.

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

   Note:

   If the desired Work Item type does not appear in the list, it means that the type does not exist in the scope where you are working. Be sure you are working in the correct scope. If you are, and the type doesn't exist, you need to configure Work Items types before configuring type-specific Enumerations.

4. In the Enumeration list, select one of the already-defined enumerations, or select Custom and enter an ID for a new enumeration to apply to this definition, then click Next. If you selected an existing Enumeration, the enumeration editor appears with the values from the all-types configuration. If you selected Custom, the enumeration editor appears with a single new empty row where you can define a new enumeration for the Work Item type you are configuring.

5. Edit the Enumeration definition in the Enumeration editor page, adding, removing, or changing values on the various table rows as desired.

6. Click Save to create a new type-specific configuration file in the repository that contains the values you defined.

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

• 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 displays 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 opens the graphical Enumeration editor page, where you can specify the enumeration values for the project scope. The editor page 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 software coding projects, and in a requirements project, the values in the global enumerations for such things as Status, Resolution, or Severity might not be suitable. Therefore, a type-specific enumeration just for Requirement items can 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 box 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 Work Items of Test Case type, but the project doesn't need that type, so the inherited type-specific enumeration could be removed from the project.

Custom fields can be of the enum (Enumeration) type. This type of field has a select-list of valid values that end users can choose. The select-list values for such custom fields must be defined in an Enumeration. Custom enum fields can only use an existing Enumeration, so you must define the relevant Enumeration before a custom field can use it.

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

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

3. In the Create New Enumeration dialog box, select which type of Work Item the enumeration is for, or choose -- unspecific -- to make it applicable to all types. Then in the Enumeration field, choose Custom and enter a file name prefix for the new Enumeration's XML file.

4. Click Next. The Enumeration editor page opens with an empty row, ready to add values to the new Enumeration.

5. Enter the desired 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 editor page for the selected field opens.

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.

Polarion comes with a set of icons for enumerations and other configurations. You can add your own icon images and use these in new enumerations, or to replace the default icons in existing enumerations.

Icon images must be 16 x 16 pixels. Supported formats are: GIF, PNG, and JPG. Custom images are saved in the Others group of the Project icon set or the Repository icon set, depending on the scope you are working in when you upload your custom image(s). Within the icon sets you can save icons in custom groups by prefacing the file name with the name of a group that it belongs to. For example, if you want to save an icon named myIcon1.png in a group named Widgets, rename the file locally as Widgets_myIcon1.png and upload the renamed file.

To upload a new custom image in an Enumeration:

1. Access the Enumeration editor page for the enumeration in the scope you want to configure (Work Items Enumerations Edit).

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

   

   ( Where custom icons appear.)

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

4. Click Upload Repository Icon or Upload Project Icon (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 the icon image. The dialog box closes and the selected icon appears in the Icon column of the Enumeration Editor.

Over time, the values specified in some enumerations may become obsolete. You can delete obsolete values, but if such values have already been used in Work Items, you may still want the values to appear in the items for your historical record for traceability and governance reasons. In this case, simply deleting a value from the configuration to keep it out of the list is not the answer.

Instead, you can select the check box in the Hidden column on the value's row in the configuration page. When this column is selected, the value still appears in the Work Items where it was used, but end users will no longer see it in the field's select list, and consequently won't be able to specify it for any new or existing Work Items.