Custom fields

You can add custom user-defined fields (UDFs) to spaces and workspaces. You can also change the display labels for system fields.

In this topic:

Add a custom field

Add a custom field to a shared space or workspace.

To add a custom field:

1. In the Settings area, select a shared space or workspace.

2. Click the Entities tab and select an entity.

3. Click the Fields tab.

4. Click + Field to add a new custom field.

5. Enter the following details: 

   Setting	Description
   Name	An internal name for the field. APIs use the name to access the field. No uppercase letters or punctuation are allowed. A suffix _udf is automatically added to the field. You can use the same name for custom fields in different entities. This can increase the number of custom fields that you can add. For details, see Custom field quota. You cannot reuse names of previously-deleted custom fields.
   Label	The field's display name. Tip: To apply the same field to related subtypes (such as Priority in manual tests and suites), create fields in all the subtypes with the same Name, Label, and Field type.
   Field type	Select a field type from the list. The following types are available: Boolean, Date and Time (in UTC format), Date, Integer, List, Long string (up to 1500 chars), Memo, String (up to 255 chars), Environment, Release, Team, User. Version 24.1 and later: The Milestone field type is available. Version 24.3 and later: The Sprint field type is available. Some of the field types are reference fields. For details, see Reference fields.
   List	For List fields: Associate the field with a list. Users will be able to select values from the selected list. For details on creating custom lists, see Lists.
   Allow multiple values	Select to allow users to select multiple values. Available for field types: List, User, Release, Team
   Description	Enter a description for the custom field. The description can be displayed as a tooltip when the user hovers over the field's label. To enable the tooltips, set the SHOW_FIELD_TOOLTIP parameter. For details, see Configuration parameters. Language support: The description text remains the same in all display languages.
   Is trendable	Select to allow the field to be included in trend widgets. Supported for all entities, except runs and tasks. Available for field types: List, Boolean, Integer, User, Team, Release, Date, Date and Time For more details, see Trendable fields.
   Include as a searchable field in a global search	For Memo and Long string fields: Select to include the field in global searches. For details, see Searchable fields.
   Add to form	You can add the field to existing custom forms. Select the forms to which to add the field. For shared space-level fields, you can select shared space-level forms. For workspace-level fields, you can select workspace-level forms.

Back to top

Reference fields

Reference fields enable you to create links between items, by referencing another item. The reference field type determines the possible values for the item. For example, the field type Release references release items, and so the available values for a Release-type field are the releases defined in the workspace or shared space.

Reference fields can reference items in the same workspace, or shared items within a shared space. For details on creating shared items, see Shared items in workspaces.

The following custom field types are reference fields: Environment, List, Release, Team, User.

Version 24.1 and later: The Milestone custom field type is available.

Version 24.3 and later: The Sprint custom field type is available.

Version 24.3 and later: You can use business rules to modify the available values for a reference field, based on a condition that you define. For details, see Modify available values for a reference field.

Back to top

Change field display labels

You can change the display names of both custom fields and system fields.

To change field labels:

1. In the Settings area, select a shared space or workspace.

2. Click Entities > Fields, and select a field.

3. Modify the Label field and click Save.

Back to top

Custom fields for subtypes

Various grids combine items of different subtypes in the same list: For example:

Grid	Subtypes
Backlog grid	Defects, user stories, quality stories
Test grid	Manual tests, BDD scenarios, Gherkin tests, model-based tests, test suites, automated tests
Run grid	Manual test runs, automated test runs

You can add the same custom field to related subtypes.

To ensure that the custom fields in the various subtypes are represented by the same grid column, create the custom field with the same settings in all the subtypes. The following settings need to match: Name, Label, Field Type.

Back to top

Trendable fields

You can define a custom field as trendable, enabling filtering and grouping by the custom field in trend widgets. This is available for all entities except runs and tasks.

Notes:

• If you define a custom field as trendable, it cannot be reverted to non-trendable. We recommend that you do not define custom fields as trendable if not necessary. Setting a large amount of custom fields as trendable has an impact on performance.

• When you define a custom field as trendable, a Trend sync status property on the custom field shows the status of synchronization. The synchronization job runs in the scope of a space, and it synchronizes all pending newly trendable custom fields within the space. There is a 10-minute delay when the job is triggered to allow the space admin to mark a set of custom fields as trendable. The delay is determined by a site parameter UDF_BECOME_TRENDABLE_SYNC_DELAY and can be modified by the admin.

• If you define the same custom field in multiple subtypes (such as user story and defect), it must be either trendable or non-trendable in all the subtypes.

Back to top

Searchable fields

By default, an item's name and description fields are searchable. You can also set additional Memo and Long String fields as searchable. For details, see Perform a global search.

The quota of searchable shared space fields and workspace fields is defined by the following parameters: 

• SEARCHABLE_UDFS_LIMIT_IN_SHARED_SPACE
• SEARCHABLE_UDFS_LIMIT_IN_WORKSPACE

By default, the maximum is 14 for shared space fields and 0 for workspace fields. The total combined quota must not exceed 20 searchable fields. For details, see Configuration parameters.

Performance effects

Setting custom fields as searchable may have the following effects on performance:

• Exceeding 15 searchable fields may affect performance.

• After you set a custom field as searchable, the data must first be indexed before it is available in a search. Indexing fields that have existed for a long time may cause performance issues. We recommend making existing custom fields searchable at a time when there is minimal usage, for example at the end of a business day or on a weekend.

Back to top

Custom field quota

Before creating user-defined fields, determine how many user-defined fields you need. Certain field types have limits on the number of user-defined fields that can be created.

The following table lists the number of allowed user-defined fields in a workspace for each field type.

Field type	Quota per workspace
Date and Time / Date	A combined total of 40 for both types
Long string	5
Memo	30 Note: You can modify this value by setting the MEMO_UDFS_LIMIT parameter. For details, see Configuration parameters.
Number	50
String / Boolean	A combined total of 100 for both types
Reference fields	Unlimited. For details, see Reference fields.

You can increase the number of custom fields beyond the quota by using the same name for custom fields in related subtypes.

Depending on your needs, you can either create identical fields, including the label and type, or create fields with the same name but different labels:

• Identical fields. Use this option if you want to add the same field to related subtypes, such as the Group field in user stories and defects. For details, see Custom fields for subtypes.

• Non-identical fields. Use this option if you want to create unique fields in related subtypes and not count towards the quota of the field type. For example, create long string fields in the user story and defect entities. In both entities, enter the same value in the Name property and different values in the Label property. It will be considered that you've used up one long string field rather than two.

  Note: In combined grids, the two fields will display under the same column, using the common Name as its title.

The following are related subtypes. Using the same name for custom fields in the different subtypes will save on your custom field quota.

Type	Related subtypes
Work items	Epics, features, user stories, quality stories, defects
Testing items	Manual tests, Gherkin tests, automated tests, test suites, BDD scenarios, model-based tests
Run items	Suite run, manual run, automated run
Release process items	Manual action, auto action, quality gate

Back to top

Delete a field

If a custom field is no longer needed, you can delete it.

Delete shared space fields from the shared space settings and workspace fields from the workspace settings.

You cannot reuse the name of a deleted field in a new custom field.

Deleting a field affects various areas:

Area	Effect
Forms	Deleted fields are removed from forms.
Rules	All rules containing the deleted field are invalid and deactivated.
Dashboard widgets	Dashboard widgets that include the deleted field react differently according to the widget type: Current status widgets. A message is displayed that the graph configuration is no longer valid. Modify the configuration as needed or remove the widget. Trend widgets. The field data remains in the graph.
Filters, Groupings, Sorts	Deleted fields are removed from filters, groupings, and sorts. A message is displayed.
Grid displays	Deleted fields are removed from the grid display without a message.
Audit log	Deleted fields remain in the server audit log.

Back to top

See also:

• Custom forms
• Lists
• Search
• Languages and labels