You can add user-defined fields to spaces and workspaces. You can also change the display labels for system fields.
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:
In the Settings area, select a shared space or workspace.
Click the Entities tab and select an entity.
Click the Fields tab.
Click + Field to add a new custom field.
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.
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.
Select a field type from the drop-down.
The following types are available: Boolean, Date and Time (in UTC format), Date, Environment, Integer, List, Long string (up to 1500 chars), Memo, Release, String (up to 255 chars), Team, User.
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
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.
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.
You can change the display names of both UDFs and system fields.
To change field labels:
In the Settings area, select a shared 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 Languages and labels.
Various grids combine items of different subtypes in the same list: For example:
|Backlog grid||Defects, user stories, quality stories|
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
You can define a UDF as trendable, enabling filtering and grouping by UDFs in trend widgets. This is available for all entities except runs and tasks.
If you define a UDF as trendable, it cannot be reverted to non-trendable. We recommend that you do not define UDFs as trendable if not necessary. Setting a large amount of UDFs as trendable has an impact on performance.
When you define a UDF as trendable, a Trend sync status property on the UDF shows the status of synchronization. The synchronization job runs in the scope of a space, and it synchronizes all pending newly-trendable UDFs within the space. There is a 10 minute delay when the job is triggered to allow the space admin to mark a set of UDFs 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 UDF in multiple subtypes (such as user story and defect), it must be either trendable or non-trendable in all the subtypes.
By default, an item's name and description fields are searchable. You can set additional Memo and Long String fields as searchable too.
For details, see Perform a global search.
The quota searchable shared space fields and workspace fields is defined by 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. For details, see Configuration parameters. The total quota must not exceed 20. Exceeding 15 searchable may affect performance.
After you enable the search for a UDF, 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 UDFs searchable at a time when there is minimal usage, for example at the end of a business day or on a weekend.
Plan ahead and determine which UDFs should be searchable. For optimal performance, enable the Include as a searchable field in a global search option for the UDFs in close proximity to one another.
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
Note: You can modify this value by setting the MEMO_UDFS_LIMIT parameter. For details, see Configuration parameters.
String / Boolean
A combined total of 100 for both types
|Environment, List, Milestone, Release, Team, User||Unlimited|
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.
|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|
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:
|Forms||Deleted fields are removed from forms.|
|Rules||All rules containing the deleted field are invalid and deactivated.|
Dashboard widgets that include the deleted field react differently according to the widget type:
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.|