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 additional 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:

  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.

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.

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.

  1. Modify the Label field and click Save.

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

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.

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

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 a global search option for the custom fields at the same time, for optimal performance.

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: