Custom fields

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

Add a custom field

Add a custom field to a shared space or workspace.

Space/workspace hierarchy. In a shared space, custom fields added at the space level are available in all its workspaces. Workspace admins can define fields that are specific to the workspace.

Workspace fields cannot have the same name or label as shared space fields.

To add a custom field:

Open the Settings menu , and select a space or workspace.
Click the Entities tab and select an entity.
Click the Fields tab.
Click Field button to add a new custom field.

Enter the field 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.
Type	Select a field type from the list. The field types include standard data fields and reference fields, which reference other workspace items. Standard data fields: Boolean, Date and Time (in UTC format), Date, Integer, Long string (up to 1500 chars), Memo, String (up to 255 chars). Reference fields: Application Module, Environment, List, Milestone, Release, Sprint, Team, User. For details on reference fields, see Reference fields.
List	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 for the field. Available for field types: Application Module, Environment, List, Milestone, Release, Sprint, Team, User.
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 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.

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.

Using custom reference fields, you can include additional information relevant to an item.

Example: Using custom fields of the type Milestone, you can:

Define multiple milestone fields for a single entity, such as a security milestone and a go-to-market milestone.
Include milestone-related information for entities that do not support a system milestone field.

Note the following when working with reference fields:

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

Change field display labels

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

To change field labels:

Open the Settings menu , and select a space or workspace.
Click Entities > Fields, and select a field.

Modify the Label field and click Save.

Tip: You can also change display labels for entities. For details, see Labels.

Custom fields for subtypes

Various grids combine items of different subtypes in the same list, as listed in the table.

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.

Example: Add the same Group field to the Defect, User Story, and Quality Story entities.

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 must match: Name, Label, Field Type.

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.

Note:

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, unless it is absolutely 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.
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.

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 might have the following effects on performance:

Exceeding 15 searchable fields can 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 might 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.

Tip: Plan ahead and determine which custom fields should be searchable. If you plan to set multiple custom fields as searchable, enable the Include as a searchable field in global search option for the custom fields at the same time, for optimal performance.

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

Delete a field

Delete custom field when they are no longer needed.

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.

When you delete a field, the following areas are affected:

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.