Configure Custom Fields overview

In addition to the default Work Item fields, you can configure custom fields of different types. For information on supported field types, see 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: 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.

Warning:

If a new *Required custom field is added to an existing Work Item Type:

If an existing Work Item type is amended so that a new custom field is *Required, then Work Items of that type created BEFORE the new field was added can still be amended without entering a value for the new field. (But you won't be able to clear a value in the field if one is already there.)

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 Coffeefrom 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 Configure Enumerations and especially the section Create Enumerations for Custom Fields.

.

Warning:

Multivalued 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