Work Items are essentially the focal point of nearly everything that goes on in Polarion. There is of course no single definition or configuration of Work Items that would be applicable to all needs everywhere, so Polarion provides the possibility to do many Work Item related customizations.
The major categories of Work Item configuration/customization are:
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 so that managers and others can see what items are planned to each one.
This configuration is available only in the Project scope, as they only apply to projects and not to all projects globally.
To create a new Time Point:
Log in with administrative rights for the Project you want to configure.
Enter the
Administration perspective.Navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select . (Note that this item only appears in the portlet when a Project is selected in the Projects portlet. It is hidden if a Project Group or Repository is selected there.)
A table appears in the top portion of the Working Area listing all Time Points currently defined for the Project (if any). The Detail pane shows the properties of the current selection in the table.
In the Working Area toolbar, click the button. A form appears in which you can specify the properties of the new Time Point.
Fill in the properties of the new Time Point and click the button to create it.
You may wish to edit the properties of an existing Time Point, to extend the Due Date or mark the Time Point closed, for example.
To edit an existing Time Point:
Navigate to the Project and select the Time Point in the Time Points table as described in Creating a New Time Point.
In the Time Point detail pane, click the button. The data in the Detail pane becomes editable.
Change the properties as desired. (You can edit all except ID.)
Click the button to save your changes.
You can only delete a Time Point if no Work Items are associated with it in their Time Point field.
A button labeled button appears beside the button described above. If any Work Items are associated with the Time Point, the 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 perspective, select the Time Point as has been described, and delete it by clicking the button which should then be enabled.
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.
To create a new Category:
Log in with administrative rights for the Project you want to configure.
Enter the
Administration perspective.Navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select . (Note that this item only appears in the portlet when a Project is selected in the Projects portlet. It is hidden if a Project Group or Repository is selected there.)
A table appears in the top portion of the Working Area listing all Categories currently defined for the Project (if any). The Detail pane shows the properties of the current selection in the table.
In the Working Area toolbar, click the button. A form appears in which you can specify the properties of the new Category.
Fill in the properties of the new Category and click the button to create it.
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:
Navigate to the Project and select the Category in the Categories table as described in Creating a New Category.
In the Category's detail pane, click the button. The data in the Detail pane becomes editable.
Change the properties as desired. (You can edit all except ID.)
Click the button to save your changes.
You can only delete a Category if no Work Items are associated with it in their Categories field.
A button labeled button appears beside the button described above. If any Work Items are associated with the Category, the button is disabled and you cannot delete the Category.
If there were ever actually a reason to delete a Time Point 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 perspective, select the Category as has already been described, and delete it by clicking the button which should then be enabled.
In addition to the standard Work Item fields, you can configure custom fields of different types (for information on supported types see Polarion Reference: Administration Reference: Custom Field Types. Custom fields can serve as a parameter for queries, providing an additional way to search for subsets of Work Items. You can define custom fields globally for all Projects, or for a specific Project. Within each scope, you can define custom fields that apply to all Work Items in the selected scope, or to one particular type of Work Item.
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 one of several possible configuration files, depending on whether you are defining custom fields applicable to all Work Items, or to a specific type of Work Item:
Table 1.1. Custom fields configuration files
| File name | Applies to |
|---|---|
custom-fields.xml | All Work Item types defined for the current scope |
task-custom-fields.xml | Task (assuming this type is defined for the current scope) |
changerequest-custom-fields.xml | Change Request (assuming this type is defined for the current scope) |
requirement-custom-fields.xml | Requirement (assuming this type is defined for the current scope) |
defect-custom-fields.xml | Defect (assuming this type is defined for the current scope) |
test-custom-fields.xml | Test (assuming this type is defined for the current scope) |
NOTE
Work Item types are defined by an enumeration configuration for each scope. Not every type cited above necessarily appears in every project or repository. For more information see Configuring Enumerations
You need to understand that initially, there is only one configuration file for custom fields: the custom-fields.xml file in the global (repository) scope. So how do you define custom fields for different Work Item types in different scopes? It's a little tricky until you grasp the concept, so let's define some common scenarios and look at what you would need to do in each case. Refer to the above table of configuration files as necessary.
Scenarios:
All Work Item types, global scope
All Work Item types, project scope
Specific Work Item type, global scope
Specific Work Item type, project scope
These scenarios assume you are working with a new installation of Polarion where instances of project scope and/or Work Item type-specific configuration files do not yet exist.
Tip
You may find it useful to create a set of folders on your local system: one for storing customized versions of configuration files for the global/repository scope, and others for storing customized versions of configuration files for different projects.
You need to work with the custom-fields.xml file for the global scope.
To access the custom-fields.xml configuration file:
Log in with global (repository) administrative rights.
Enter the
Administration perspective.Select Repository in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the custom-fields.xml link in the Custom Field Definitions portlet to download the configuration file to your local system.
After editing the file, use the controls in the Upload New Global Custom Field Definition portlet to upload the modified file back to the Polarion repository.
To configure custom fields in the project scope that apply to all Work Item types, you need to download the global configuration file, make a copy of it in a different, appropriately named location on your local system), edit it, and upload the modified version back to Polarion.
To create a project-specific custom fields configuration:
Log in with administration rights for the Project you want to configure.
Enter the
Administration perspective.In the Projects portlet, select the Project you want to configure.
In the Topics portlet, expand the node and select .
Use the custom-fields.xml link in the Custom Field Definitions portlet to download the configuration file to the location on your local system where you want to store the project-specific version of the configuration file.
Edit the
custom-fields.xmlfile as necessary to define the custom fields you want for the Project.Important
Do not rename the file. It is the file name that tells Polarion that this is a configuration for all Work Items. The location in the repository indicates that it is a configuration only for the Project.
Return to the Polarion user interface. In the Upload New Project Custom Field Definition portlet, click the button to select the file you just finished editing for the Project configuration.
Click the button to upload the edited file to the repository.
To configure custom fields for a specific Work Item type globally, you need to download a copy of the global configuration file (custom-fields.xml), rename it with the correct file name for the type of Work Item that is to have the new custom field(s), and upload the modified file back to Polarion.
To perform this configuration:
Log in with global administrative rights.
Enter the
Administration perspective.Select Repository in the Projects portlet.
In the Topics portlet, expand the node and select . Note that the Working Area contains a table that lists the types of Work Items currently defined for the repository (i.e., the default for all Projects).
Use the custom-fields.xml link in the Custom Field Definitions portlet to download the configuration file to the location on your local system where you want to store the global version of the configuration file.
Rename the downloaded file with the correct filename for the type of Work Item you are configuring. Refer to the table of configuration file names above.
After editing the renamed file, use the controls in the Upload New Global Custom Field Definition portlet to upload the modified file back to the Polarion repository.
After this upload, the file name value in the File Name column of the row corresponding to the Work Item type becomes a link.
Let's say you wanted to define custom fields in the global scope for Task type Work Items. You would:
Download the
custom-fields.xmlfile to an appropriately labeled location your local system.Rename
custom-fields.xmlastask-custom-fields.xml.Edit the renamed file to define the desired custom field(s).
Go back to Polarion and upload
task-custom-fields.xml.
To configure custom fields for a specific Work Item type for a specific Project, you need to download a copy of the global configuration file (custom-fields.xml), rename it with the correct file name for the type of Work Item that is to have the new custom field(s), and upload the modified file back to Polarion making sure you do this while working the project scope of the Administration perspective.
To perform this configuration:
Log in with administrative rights for the Project you want to configure.
Enter the
Administration perspective.In the Projects portlet, select the Project you want to configure.
In the Topics portlet, expand the node and select . Note that the Working Area contains a table that lists the types of Work Items currently defined for the Projects.
Use the custom-fields.xml link in the Custom Field Definitions portlet to download the global configuration file to the location on your local system where you want to store the project-specific version of the configuration file.
Rename the downloaded file with the correct filename for the type of Work Item you are configuring. Refer to the table of configuration file names above.
After editing the renamed file, use the controls in the Upload New Global Custom Field Definition portlet to upload the modified file back to the Polarion repository.
Important
Be sure you still have the Project selected in the Projects portlet. The Repository node should not be selected! If it is, you will make the configuration in the wrong scope.
After this upload, the file name value in the File Name column of the row corresponding to the Work Item type becomes a link.
Let's say you wanted to define custom fields in the project scope for Requirement type Work Items. You would:
Download the
custom-fields.xmlfile to an appropriately labeled location your local system.Rename
custom-fields.xmlasrequirement-custom-fields.xml.Edit the renamed file to define the desired custom field(s).
Go back to Polarion, making sure the Project is still selected, and upload
requirement-custom-fields.xml.
Live Documents are a feature of Enterprise level products only.
It is possible to map to custom fields in an Excel Live Document template. The easiest way is the following:
Create a new Excel Live Document from a Live Document template.
Define the desired custom fields in the configuration of the project where you created the Live Document.
Create a Work Item in the newly created Live Document via the Polarion web interface.
This way you get columns for the desired custom fields generated in the Live Document. You can optionally delete the new Work Item from it and then use it as a template for other Live Documents in other projects later on.
The required attribute of the <field> element in the custom-fields.xml configuration file enables you to specify whether the user must fill in a value for the field when creating a Work Item that has the custom field. Setting the value to true makes the field required. Polarion checks for this attribute and if enabled, does not allow creation of a new Work Item unless the field contains a value.
You may remove a custom field from the configuration, or change its type. However, this can cause some problems with the system caches, which is why the button is provided on the Custom Fields configuration page (Administration: Work Items: Custom Fields). After uploading a configuration is which you have removed a custom field or changed its type, you should click this button to ensure proper updating for all users.
Important
You should not use after such changes adding a new custom field, or making a simple name change, as this will slow server performance until the caches are refilled.
Clearing caches is required if a custom field is removed or its type changed.
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. By default this field has a list with the following options, which reflect the default workflow configuration:
OpenAcceptedIn ProgressReopenedResolvedClosed
These values are defined, and can be customized for different scopes, in an XML enumeration configuration file. This section describes the various enumeration configuration files, which Work Item fields they apply to, and how to access the configuration files. The XML structure of the different configuration files is covered in the Administration Reference: Enumerations.
The following table lists Work Item fields that display enumerations and the name of the enumeration configuration file where the options are defined.
Table 1.2. Work Item Fields and Enumeration Configuration Files
| Work Item Field | Configuration Filename |
|---|---|
| Status | status-enum.xml |
| Priority | priority-enum.xml |
| Role (for Hyperlink) | hyperlink-role-enum.xml |
| Link Role | workitem-link-role-enum.xml |
| Type (of Work Item) | workitem-type-enum.xml |
| Resolution | resolution-enum.xml |
| Severity | severity-enum.xml |
| Risk | risk-enum.xml |
Procedures for accessing these files are covered in subsequent sections of this document.
Existing enumerations can be edited online in the portal. The following enumerations can be edited by means of graphical UI controls: severity values, status values, priority values, resolution values, and Work Item types.
The remaining enumerations are configured by editing the relevant XML file. You can optionally do that in a dedicated text editor control provided in the respective enumeration configuration pages of the Polarion web portal (Administration perspective).
Configuration of enumerations 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 of each enumeration is specified in the respective configuration file described in the previous section. The following sections explain how to access each file.
Within each scope (repository or project), enumerations can be configured by Work Item type. For example, in some project, you might decide you need to add an additional resolution value "Postponed" to Requirements, but not Tasks, Defects, and Change Requests.
The Status enumeration defines values for the Status field of Work Items. You can modify the configuration in the global (repository) scope where changes will affect all Projects, or for a specific Project. Examples of customizations you might do include changing the name of an existing option (e.g. "Completed" instead of "Resolved"), removing an option (e.g. maybe your process needs only "Closed" and not "Resolved"), or adding a new option- "Testing", for example.
To access the status-enum.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the link
status-enum.xmlin the table which appears in the Enumerations portlet to download the configuration file to your local system, or clickeditin the Actions column to edit online.If you want to do this configuration for some particular Work Item type(s), but not ALL types, see Type-specific Configuration below.
After modifying and/or making one or more copies of the file for type-specific configuration, use the controls in the Upload New [Global][Project] Enumeration portlet to upload the modified file(s) back to the Polarion repository.
If you want to perform configuration of Status values for one or more specific Work Item types, but not for ALL types, you need to create a copy of the status-enum.xml for each Work Item type for which you want to customize Status values, naming each file copy according to the convention described below. You then edit each copy, making the modification(s) you require for each Work Item type, and then you upload all the named modified copies of status-enum.xml to the Polarion server via the Enumerations page.
Important
The ID of each option in the configuration file(s) should be unique among IDs of the enumeration's options active in the project. If there are two options with the same ID, Polarion assumes that they represent the same option. (Different IDs can have the same label and icon.)
If you want to modify status-enum.xml and have changes apply to all Work Item types, you don't need to rename the file or make a copy. If you are configuring for different Work Item types, you need to create the relevant copies of status-enum.xml named this way:
For Tasks:
task-status-enum.xmlFor Change Requests:
changerequest-status-enum.xmlFor Requirements:
requirement-status-enum.xmlFor Defects:
defect-status-enum.xmlFor custom Work Item type:
[custom type ID]-status-enum.xml
Again, if you are customizing Status for ALL Work Item types, just modify and upload status-enum.xml; if you are customizing it for one or more Work Item types, make copies named as above for only those types you are customizing (i.e. not for all of those in the list above).
The Priority enumeration defines values for the Priority field of Work Items. You can modify the configuration in the global (repository) scope where changes will affect all Projects, or for a specific Project. Examples of customizations you might do include changing the name of an existing option (e.g. "Maximum" instead of "Highest") or removing an option (e.g. maybe your process needs only "Low" and not "Lowest").
To access the priority-enum.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the link
priority-enum.xmlin the table which appears in the Enumerations portlet to download the configuration file to your local system, or clickediti n the Actions column to edit online.If you want to do this configuration for some particular Work Item type(s), but not ALL types, see Type-specific Configuration below.
If you are editing the configuration file offline, use the controls in the Upload New [Global][Project] Enumeration portlet to upload the modified file back to the Polarion repository.
If you want to perform configuration of Priority values for one or more specific Work Item types, but not for ALL types, you need to create a copy of the priority-enum.xml for each Work Item type for which you want to customize Status values, naming each file copy according to the convention described below. You then edit each copy, making the modification(s) you require for each Work Item type, and then you upload all the named modified copies of priority-enum.xml to the Polarion server via the Enumerations page.
Important
The ID of each option in the configuration file(s) should be unique among IDs of the enumeration's options active in the project. If there are two options with the same ID, Polarion assumes that they represent the same option. (Different IDs can have the same label and icon.)
If you want to modify priority-enum.xml and have changes apply to all Work Item types, you don't need to rename the file or make a copy. If you are configuring for different Work Item types, you need to create the relevant copies of priority-enum.xml named this way:
For Tasks:
task-priority-enum.xmlFor Change Requests:
changerequest-priority-enum.xmlFor Requirements:
requirement-priority-enum.xmlFor Defects:
defect-priority-enum.xmlFor custom Work Item type:
[custom type ID]-priority-enum.xml
Again, if you are customizing Status for ALL Work Item types, just modify and upload priority-enum.xml; if you are customizing it for one or more Work Item types, make copies named as above for only those types you are customizing (i.e. not for all of those in the list above).
The enumeration for Hyperlink defines values for the Role field of the Hyperlinks portlet of Work Items. You can modify the configuration in the global (repository) scope where changes will affect all Projects, or for a specific Project. To understand what kind of customization you might want to do, you should understand the purpose and usage of Hyperlinks and Hyperlink Roles. This is covered in the User Guide: Work Item Hyperlinks and Hyperlink Roles.
To access the hyperlink-role-enum.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the link
hyperlink-role-enum.xmlin the table which appears in the Enumerations portlet to download the configuration file to your local system, or clickeditin the Actions column to edit online.If you want to do this configuration for some particular Work Item type(s), but not ALL types, see Type-specific Configuration below.
If you edit the file offline, use the controls in the Upload New [Global][Project] Enumeration portlet to upload the modified file back to the Polarion repository.
If you want to perform configuration of Status values for one or more specific Work Item types, but not for ALL types, you need to create a copy of the hyperlink-role-enum.xml for each Work Item type for which you want to customize Status values, naming each file copy according to the convention described below. You then edit each copy, making the modification(s) you require for each Work Item type, and then you upload all the named modified copies of hyperlink-role-enum.xml to the Polarion server via the Enumerations page.
Important
The ID of each option in the configuration file(s) should be unique among IDs of the enumeration's options active in the project. If there are two options with the same ID, Polarion assumes that they represent the same option. (Different IDs can have the same label and icon.)
If you want to modify hyperlink-role-enum.xml and have changes apply to all Work Item types, you don't need to rename the file or make a copy. If you are configuring for different Work Item types, you need to create the relevant copies of hyperlink-role-enum.xml named this way:
For Tasks:
task-hyperlink-role-enum.xmlFor Change Requests:
changerequest-hyperlink-role-enum.xmlFor Requirements:
requirement-hyperlink-role-enum.xmlFor Defects:
defect-hyperlink-role-enum.xmlFor custom Work Item type:
[custom type ID]-hyperlink-role-enum.xml
Again, if you are customizing Status for ALL Work Item types, just modify and upload hyperlink-role-enum.xml; if you are customizing it for one or more Work Item types, make copies named as above for only those types you are customizing (i.e. not for all of those in the list above).
The Link Role enumeration defines values for the Role field of the Linked Work Items portlet of Work Items. This field is used to define relationships between linked Work Items, such as dependency. You can modify the configuration in the global (repository) scope where changes will affect all Projects, or for a specific Project. Examples of customizations you might do include changing the name of an existing option (e.g. "parent of" instead of "parent") or removing an option (e.g. maybe your process doesn't needs to define a "has follow-up" relationship).
To access the workitem-link-role-enum.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the link
workitem-link-role-enum.xmlin the table which appears in the Enumerations portlet to download the configuration file to your local system, or clickeditin the Actions column to edit online.If you want to do this configuration for some particular Work Item type(s), but not ALL types, see Type-specific Configuration below.
if you edit the file offline, use the controls in the Upload New [Global][Project] Enumeration portlet to upload the modified file back to the Polarion repository.
If you want to perform configuration of Work Item Link Role values for one or more specific Work Item types, but not for ALL types, you need to create a copy of the work-item-link-role-enum.xml for each Work Item type for which you want to customize Status values, naming each file copy according to the convention described below. You then edit each copy, making the modification(s) you require for each Work Item type, and then you upload all the named modified copies of work-item-link-role-enum.xml to the Polarion server via the Enumerations page.
Important
The ID of each option in the configuration file(s) should be unique among IDs of the enumeration's options active in the project. If there are two options with the same ID, Polarion assumes that they represent the same option. (Different IDs can have the same label and icon.)
If you want to modify work-item-link-role-enum.xml and have changes apply to all Work Item types, you don't need to rename the file or make a copy. If you are configuring for different Work Item types, you need to create the relevant copies of work-item-link-role-enum.xml named this way:
For Tasks:
task-work-item-link-role-enum.xmlFor Change Requests:
changerequest-work-item-link-role-enum.xmlFor Requirements:
requirement-work-item-link-role-enum.xmlFor Defects:
defect-work-item-link-role-enum.xmlFor custom Work Item type:
[custom type ID]-work-item-link-role-enum.xml
Again, if you are customizing Status for ALL Work Item types, just modify and upload work-item-link-role-enum.xml; if you are customizing it for one or more Work Item types, make copies named as above for only those types you are customizing (i.e. not for all of those in the list above).
The Work Item Type enumeration defines the types of Work Items which appear in the Topics portlet (Projects perspective) and the Create menu in the Work Items table view. By default, 3 types are defined:
Task
Change Request
Requirement
Examples of customizations you might do include renaming an existing type (e.g. "Job" instead of "Task"), removing an existing type (e.g. maybe your organization doesn't have formal Requirements, so you remove that type), or adding another type: "Bug" or "Defect", for example.
To access the workitem-types-enum.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the link
workitem-type-enum.xmlin the table which appears in the Enumerations portlet to download the configuration file to your local system, or clickeditin the Actions column to edit online..If you edit the file offline, use the controls in the Upload New [Global][Project] Enumeration portlet to upload the modified file back to the Polarion repository.
The Resolution enumeration defines values for the Resolution field of Work Items. You can modify the configuration in the global (repository) scope where changes will affect all Projects, or for a specific Project. Examples of customizations you might do include changing the name of an existing option (e.g. "Deferred" instead of "Later"), removing an option (e.g. maybe your process doesn't needs the "Incomplete" option), or adding a new option, "Obsolete" for example.
To access the resolution-enum.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the link
resolution-enum.xmlin the table which appears in the Enumerations portlet to download the configuration file to your local system, or clickeditin the Actions column to edit online.If you want to do this configuration for some particular Work Item type(s), but not ALL types, see Type-specific Configuration below.
If you edit the file offline, use the controls in the Upload New [Global][Project] Enumeration portlet to upload the modified file back to the Polarion repository.
If you want to perform configuration of Resolution values for one or more specific Work Item types, but not for ALL types, you need to create a copy of the resolution-enum.xml for each Work Item type for which you want to customize Status values, naming each file copy according to the convention described below. You then edit each copy, making the modification(s) you require for each Work Item type, and then you upload all the named modified copies of resolution-enum.xml to the Polarion server via the Enumerations page.
Important
The ID of each option in the configuration file(s) should be unique among IDs of the enumeration's options active in the project. If there are two options with the same ID, Polarion assumes that they represent the same option. (Different IDs can have the same label and icon.)
If you want to modify resolution-enum.xml and have changes apply to all Work Item types, you don't need to rename the file or make a copy. If you are configuring for different Work Item types, you need to create the relevant copies of resolution-enum.xml named this way:
For Tasks:
task-resolution-enum.xmlFor Change Requests:
changerequest-resolution-enum.xmlFor Requirements:
requirement-resolution-enum.xmlFor Defects:
defect-resolution-enum.xmlFor custom Work Item type:
[custom type ID]-resolution-enum.xml
Again, if you are customizing Status for ALL Work Item types, just modify and upload resolution-enum.xml; if you are customizing it for one or more Work Item types, make copies named as above for only those types you are customizing (i.e. not for all of those in the list above).
The Severity enumeration defines values for the Severity field of Work Items. You can modify the configuration in the global (repository) scope where changes will affect all Projects, or for a specific Project. Examples of customizations you might do include changing the name of an existing option (e.g. "Stopship" instead of "Blocker"), removing an option (e.g. maybe your process doesn't needs the "Trivial" option), or adding a new option, "Time Permitting" for example.
To access the severity-enum.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the link
severity-enum.xmlin the table which appears in the Enumerations portlet to download the configuration file to your local system, or clickeditin the Actions column to edit online..If you want to do this configuration for some particular Work Item type(s), but not ALL types, see Type-specific Configuration below.
If you edit the file offline, use the controls in the Upload New [Global][Project] Enumeration portlet to upload the modified file back to the Polarion repository.
If you want to perform configuration of Status values for one or more specific Work Item types, but not for ALL types, you need to create a copy of the severity-enum.xml for each Work Item type for which you want to customize Status values, naming each file copy according to the convention described below. You then edit each copy, making the modification(s) you require for each Work Item type, and then you upload all the named modified copies of severity-enum.xml to the Polarion server via the Enumerations page.
Important
The ID of each option in the configuration file(s) should be unique among IDs of the enumeration's options active in the project. If there are two options with the same ID, Polarion assumes that they represent the same option. (Different IDs can have the same label and icon.)
If you want to modify severity-enum.xml and have changes apply to all Work Item types, you don't need to rename the file or make a copy. If you are configuring for different Work Item types, you need to create the relevant copies of severity-enum.xml named this way:
For Tasks:
task-severity-enum.xmlFor Change Requests:
changerequest-severity-enum.xmlFor Requirements:
requirement-severity-enum.xmlFor Defects:
defect-severity-enum.xmlFor custom Work Item type:
[custom type ID]-severity-enum.xml
Again, if you are customizing Status for ALL Work Item types, just modify and upload severity-enum.xml; if you are customizing it for one or more Work Item types, make copies named as above for only those types you are customizing (i.e. not for all of those in the list above).
The Risk enumeration defines values for the Risk field of Work Items. You can modify the configuration in the global (repository) scope where changes will affect all Projects, or for a specific Project. Examples of customizations you might do include changing the value Low" to "Negligible" (or other term used by your organization), or adding another risk level definition like "Certain Doom" or whatever you need to express the concept to your team.
To access the risk-enum.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the link
risk-enum.xmlin the table which appears in the Enumerations portlet to download the configuration file to your local system, or clickeditin the Actions column to edit online.If you want to do this configuration for some particular Work Item type(s), but not ALL types, see Type-specific Configuration below.
If you edit the file offline,, use the controls in the Upload New [Global][Project] Enumeration portlet to upload the modified file back to the Polarion repository.
If you want to perform configuration of Status values for one or more specific Work Item types, but not for ALL types, you need to create a copy of the risk-enum.xml for each Work Item type for which you want to customize Status values, naming each file copy according to the convention described below. You then edit each copy, making the modification(s) you require for each Work Item type, and then you upload all the named modified copies of risk-enum.xml to the Polarion server via the Enumerations page.
Important
The ID of each option in the configuration file(s) should be unique among IDs of the enumeration's options active in the project. If there are two options with the same ID, Polarion assumes that they represent the same option. (Different IDs can have the same label and icon.)
If you want to modify risk-enum.xml and have changes apply to all Work Item types, you don't need to rename the file or make a copy. If you are configuring for different Work Item types, you need to create the relevant copies of risk-enum.xml named this way:
For Tasks:
task-risk-enum.xmlFor Change Requests:
changerequest-risk-enum.xmlFor Requirements:
requirement-risk-enum.xmlFor Defects:
defect-risk-enum.xmlFor custom Work Item type:
[custom type ID]-risk-enum.xml
Again, if you are customizing Status for ALL Work Item types, just modify and upload risk-enum.xml; if you are customizing it for one or more Work Item types, make copies named as above for only those types you are customizing (i.e. not for all of those in the list above).
Note
Configurable workflow may not be available in some Polarion ALM products.
A "workflow" is a set of statuses and status transitions, transition conditions and dependencies that a Work Item passes through in its life cycle. For example, consider the default set of statuses:
Open (the default status for all new items)
Start Progress
Resolve
Resolve and Close
If you change the status from Open to Start Progress, or Open to Resolve, this triggers a status transition.
You can customize workflows and transitions in several scopes: globally (for all Projects), project-specific for individual Projects, or Project + type-specific, which applies only to a specific type of Work Item in a Project. Polarion looks for the most specific workflow definition first and proceeds toward the most generic in the following search sequence:
Project-specific and Work Item type-specific
Global and Work Item type-specific
Project-specific
Global
As with other configurations, configuration data is stored in XML configuration files and it is possible to modify the configuration by directly editing those files. Information about these files and their location can be found in the Administrator's Reference.
However, beginning with version 2.5, Polarion provides a graphical Workflow Designer. You can use this tool to customize workflows in any of the available scopes. Following sections describe how to access the Workflow Designer and its structure.
Before you invoke the Workflow Designer tool, you need to navigate in the Administration perspective to the access point for the scope you want to customize (global, Project-specific, etc.)
If you want to modify global workflows (i.e. for all Projects), select the Repository node in the Projects portlet. Keep in mind that modifications will apply to both new Projects and all existing Projects unless a customized configuration is defined for them individually.
If you want to modify workflows for a specific Project, select that Project's node in the Projects portlet. (Don't forget, we are talking about the Administration perspective ).
Once you have selected the configuration scope in the Projects portlet, go to the Topics portlet, expand the Work Items node, and select .
The Working Area displays 2 portlets. The Workflow Definitions portlet displays a table of workflow configurations for different Work Item types. If you are in the project scope, the table also has a row for a project-specific configuration for all Work Items. In both global and project scope, the table provides access to the global configuration for all work items as well.
The Upload New Project Workflow Definition portlet provides controls for uploading locally modified XML configuration files if you should choose to do the workflow configuration that way.
Please refer to the following figure while reading the information in this section.
The Transitions portlet at the top of the Workflow Designer is a matrix of workflow transitions. 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" state to the "Resolved" state. At each intersection where a transition is possible, there is a drop-down list of actions which can take place when the transition is triggered. These actions are defined in the Actions portlet.
The next portlet, States, is an enumeration editor for workflow states. When editing a Project workflow when there is not yet a project-scope status-enum.xml file, this portlet is in read-only mode. Click the button to switch the portlet into edit mode.
Next, as you scroll downward, is the Actions portlet, which is an editor for Transition Actions. The Actions used by 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, not collection or structure types. The Actions column contains 2 icons. The Edit icon (white check mark in purple circle) displays a popup editor of the action details (conditions and functions) which are already specified.
In the Required Roles field you can enter a comma-separated list of roles that a user has to have 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 roleworkitem.author- only author of the work item has this role
Valid role names are all global and project roles (admin, user, project-admin 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 logic role is workitem.assignee. Roles are OR-ed (one is enough for the condition to succeed).
For a listing of the available conditions for this configuration and functions that can be specified, see Administration Reference: Workflow Conditions and Functions
You can configure the data columns that display in the Work Items Table view. 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 Table view customization is done by editing the table-settings.xml file for the scope you want to customize, and then uploading the modified file back to the Polarion server.
The configuration file contains <column> tags for all the available data fields that can be displayed in the Table view. 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 view, 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 view, 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.
To access the table-settings.xml file:
Log in with the necessary administrative permissions and enter the
Administration perspective.In the Projects portlet, either select the Repository node, or if making a Project configuration, select the relevant Project.
In the Topics portlet, expand the node and select .
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 portlet 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 node in the Projects portlet before invoking the Table Configuration dialog.
In a new, clean installation the fields available to display as Table view 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 Table view. 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 1.3. Fields that can be displayed as Table view columns
| Field ID | Shown 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.
You can customize the list of queries that serve as search parameters in the and field in the Search Bar of the Work Items table ( Projects perspective ).
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:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the appropriate link in the Configuration portlet to download the configuration file to your local system, or use the online configuration editor to modify the configuration.
If you edit the file offline, use the controls in the Upload New [Project][Global] Configuration portlet to upload the modified file back to the Polarion repository.
Shortcuts are essentially saved queries that aggregate some subset of all Work Items in the repository. For information on using shortcuts, see the User Guide: Using Queries and Shortcuts.
Shortcuts can be configured in 3 scopes:
Global (repository): visible to and usable by all users in all Projects
Project: visible to and usable by all users of a Specific project
User: visible to and usable by the individual user who created the shortcut
Shortcuts appear in the Shortcuts portlet of the main navigation panel grouped according to scope. Clicking on the display name executes the query and retrieves the relevant Work Items.
The process of defining a new Shortcut looks like this:
Log in to Polarion with access rights for the scope you want to configure (Global/repository, Project)
Select the Repository node in the Projects portlet if creating a Global shortcut; select a Project if creating a project-specific shortcut.
Use the Query Builder in the Work Items table to define a query that accesses the Work Items you want the new Shortcut to access.
Save the query as a shortcut, giving it a name and defining its scope.
To create a new shortcut:
In the scope you want to create the shortcut for, navigate to the Work Items Table view.
Use the Query Builder in the Work Items table to define a query that accesses the Work Items you want the new Shortcut to access and execute the query by clicking the button.
In the search bar at the far right, click the Save as Shortcut icon. The Save as Shortcut popup appears.
Select the scope of the Shortcut in the Scopes list.
Type a descriptive name in the Name field.
If you want the Shortcut to include the current Project selection, check the
Include project selectionoption.Click the button to save the new Shortcut.
The new Shortcut now appears in the section for its scope in the Shortcuts portlet.
To delete a Shortcut:
In the
Projectsperspective, select the Shortcut you want to remove in the Shortcuts portlet of the main navigation panel. Note that you must have access rights for the scope of the existing shortcut.In the title bar of the Shortcuts portlet, click the Customize icon (the center one in the icon group). The Saved Shortcuts popup appears listing the shortcuts available according to your current access rights and scope selection.
In the table, locate the row for the Shortcut you want to delete, and in the Actions column, click the - (minus sign) icon. The Shortcut name now appears in strike-through font.
Click the button to delete the marked Shortcut.
NOTE: The Working Calendar feature may not be present in some Polarion ALM products.
The Working Calendar feature enables Polarion ALM's 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 perspective, 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 perspective. 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.
This section describes how to access the global Working Calendar, and a user's Working Calendar in the Administration Perspective. 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:
Enter the Administration perspective.
In the
Projects portlet, click on Repository.In the
Topics portlet, expand the Work Items node and click on Working Calendar.
To access a user configuration:
Enter the Administration perspective.
In the
Projects portlet, click on Repository.In the
Topics portlet, expand the User Management node and click on Users.Use the Search feature to locate the user whose Working Calendar you want to configure.
In the user account preview pane (bottom of the screen), scroll downwards, locate the button and click it to display the selected user's personal Working Calendar.
The Working Calendar page consists of the following 2 portlets:
Regular Schedule
Schedule Exceptions
This portlet defines the "normal" work schedule for your organization. In a new installation, the defaults are set as follows:
Start Time:
09:00End Time:
17:00Days 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:
Change the Start Time and/or End Time value(s) as desired.
Click the button in the toolbar above the portlet.
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 button.
In the Schedule Exceptions portlet 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:
Enter a meaningful title for the exception in the Title field. For example:
New Years Day Holiday.Select the exception type by choosing a value in the Type drop-down list. For example: .
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.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.
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 .
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.
If you want to add another Schedule Exception, click the + (plus sign) in the Actions column and repeat the above steps on the new row that appears.
When you are finished defining your Schedule Exception(s), click the button in the Working Calendar toolbar. To cancel all changes, click the button.
To remove a Schedule Exception:
Click the - (minus sign) icon in the Actions column of the exception you want to remove.
Click the button in the Working Calendar toolbar. To cancel the remove (before any Save), click the button.
You can configure certain defaults for the Live Plan project planning engine:
Default initial time estimate value
Query that determines which Work Items are processed by Live Plan
Default roles for dependency and parent relationships for linked Work Items
Default number of working hours in a working day
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 planning.xml configuration file. You will find comments in this file that explain the elements and their usage.
To access the planning.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the appropriate link in the Configuration portlet to download the configuration file to your local system, or edit online with the text editor provided.
If you edit the file offline, use the controls in the Upload New [Project] Configuration portlet to upload the modified file back to the Polarion repository.
There is a per-project option in the planning.xml file, workitem-splitting, that defines whether Work Items in a project can be split. The option is enabled by default.
If the option is enabled, then when Polarion searches for a space for a Work Item in the project plan, it may decide to split the Work Item to 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.
The due-date-planning option controls the way in which the Live Plan engine processes and renders the due date of Work Items. The default value is false. This configuration is available in the global scope only. Changing the value to true 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.
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 due-date-planning option turned on.
You can configure the default state of the Suspect check box in Work Item link properties.
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 linking.xml configuration file. You will find comments in this file that explain the elements and their usage.
To access the linking.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the appropriate link in the Configuration portlet to download the configuration file to your local system, or edit online with the text editor provided.
If you edit the file offline, use the controls in the Upload New [Project] Configuration portlet to upload the modified file back to the Polarion repository.
You can configure Polarion to automatically assign new Work Items to someone- a project leader, for example. This automatic assignment is not active by default- you need to perform this configuration to activate it.
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 autoassignment.xml configuration file. You will find comments in this file that explain the elements and their usage.
Suppose you want to configure Polarion to automatically assign new Work Items to the user who is defined as project lead. You would need to add the following lines to the autoassignment.xml file in the project scope, inside the <autoassignment> element:
<rule>
<condition>
<!-- empty condition is always satisfied -->
</condition>
<assignee>
<project-lead />
</assignee>
</rule>
To access the autoassignment.xml configuration file:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the appropriate link in the Configuration portlet to download the configuration file to your local system, or edit online with the text editor provided.
If you edit the file offline, use the controls in the Upload New [Global][Project] Configuration portlet to upload the modified file back to the Polarion repository.
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:
Log in with administrative rights for the scope you want to configure (repository and/or Project).
Enter the
Administration perspective.If making a global configuration, select Repository in the Projects portlet. If making a project configuration, navigate to and select the Project in the Projects portlet.
In the Topics portlet, expand the node and select .
Use the appropriate link in the Configuration portlet to download the configuration file to your local system, or edit online with the text editor provided.
If you edit the file offline, use the controls in the Upload New [Project] Configuration portlet to upload the modified file back to the Polarion repository.