Custom Field Types

A custom field type is a format that is assigned to values that are stored in the field. This format determines how YouTrack interprets the data.

Supported types can be divided into two categories:

Simple types — these types include text, period, date, date and time, integer, and string types.
Enumerated types — these types let you select values from a predefined list.

Simple Types

Simple types store single values in a specific format.

Field Type	Description
`string`	Stores a single value as a string of characters. String-type fields automatically recognize when the value entered in the field is a URL. When you enter a web address into a field that stores a string, YouTrack displays a special icon next to the value in the field. Users can click this icon to open the target link in a new browser tab.
`text`	Stores a string of characters that is interpreted in Markdown syntax when shown in the issue. Fields with this type are not shown in the sidebar with other custom fields. Instead, they appear just below the issue description. As with the issue summary and description, you can only change the values for text-based fields when an issue is open in create or edit mode. When editing these fields, a preview of the input is shown as formatted in Markdown.
`date`	Stores a single value in a date format. Users set and change the value by selecting a date with a calendar control. The date is presented in the format that the current user has selected in the Date format setting on the Profile page.
`date and time`	Stores a single value in a date format. The complete date and time are shown in the custom field. Users set and change the value with an input field. The date and time are presented in the format that the current user has selected in the Date format setting on the Profile page.
`period`	Stores a value that represents a period of time. Fields that store data as a period type are used for time tracking.
`integer`	Stores a single value as an integer.
`float`	Stores a single value as a floating-point number.

Enumerated Types

Enumerated types store one or more values from a predefined set of values. For many of these types, you can assign additional properties to each of the values in the set. For more information, see Value-specific Settings.

Fields that store a state type can only store single values. You can configure any of the other enumerated types to store single or multiple values.

Field Type	Description
`enum`	Stores values from a predefined set of values. The set of values for this type of field is an arbitrary array of values that are stored as a `string` type.
`group`	Stores a reference to a group. The set of possible values is taken from the list of groups in YouTrack. The custom field displays the group name. The list of available groups is based on the Read Group permission assignment.
`user`	Stores a reference to a user account. The default Assignee field uses this type. The set of possible values is taken from the list of users in YouTrack. The custom field displays the full name. The drop-down list also displays the username. The list of available users is based on the Read User permission assignment.
`ownedField`	Stores values from a predefined set of values. The default Subsystem field uses this type. This type is similar to the `enum` type, except that each value in the set of values stores an `owner`. This property stores a reference to the user who is responsible for the subsystem as a `user` type.
`state`	Stores the state of an issue from a predefined set of issue states. This type is also a variation of the `enum` type. Here, each value in the set of values has an `isResolved` property. This property indicates whether the issue is considered to be resolved when it is assigned the corresponding value in this field. This value is stored as a `Boolean` type. For more information about this type, see Possible Conflicts with Multiple State-type Fields.
`version`	Stores a version from a predefined list of versions. Each value in the set of versions stores the following information: `releaseDate` — stores the release date as a `date` type. Can correspond to the actual or scheduled release date. `released` — indicates whether the version is released, stored as a `Boolean` type. `archived` — indicates whether the version is archived, stored as a `Boolean` type. If a version is flagged as archived, it is no longer visible in the list of values for a custom field. This means that you cannot select and add the value to the field or select and remove a value from a field. Archived versions are still available to commands, workflows, and the REST API. This means that you can use commands to add or remove archived values or update these values programmatically.
`build`	Stores a build number from a predefined set of build numbers. Each value in the set of builds stores an `assembleDate`. This property stores the date when the selected build was assembled as a `date` type.

Possible Conflicts with Multiple State-type Fields

If you add more than one custom field that uses a state type to your projects, you can create some undesired results. Your issues are not resolved until all state-type fields are assigned values that are considered to be resolved. Unless your users are informed about this requirement, confusion arises. When they update the value of one state field to resolve an issue, the visual presentation of the issue remains unchanged — not dimmed with strikethrough text for the issue ID as is expected for resolved issues.

For this reason, we strongly advise against using more than one state field in a project.

If you weren't lucky enough to have read this warning before you created issues in your projects, there's still hope. The following solutions can help you get the functionality you want without annoying your team.

The easiest workaround is to mark all the values for all extra state-type fields as resolved. Your users only have to manage the values in a single custom field to determine whether the issue is resolved or not.
The preferred solution is to convert extra state-type fields to fields that use a generic enumerated type. This makes the resolved state dependent on the values for a single custom field.
To learn more about changing field types, see Change Field Type.

There are some situations where you might not be able to resolve the problem with either of these solutions. For example, if the extra state fields are shared with other projects where it is the only state-type field, you would have problems with issues in these projects. In this case, consider migrating the values that are currently stored in extra state-type fields to new fields that store data as a different type.

To migrate values to another field:

Open the Administration > Custom Fields page.
Locate the project that contains extra state-type custom fields.
Click the Add field to project button.
Use the settings to define a custom field that stores an enum type.
Add the same values to the new custom field that are used in one of the extra state-type custom fields.
When finished, update the values that are stored in the custom fields for your project:
- From the Issues list, enter a search query that finds all the issues that contain a specific value in the state-type custom field. Start with the first value in the set. For example: In #{Project} Status: Submitted.
- Select all the issues that are returned by the search query. Use the keyboard shortcut Ctrl + A (⌘ + A on macOS) to select all the issues that are returned by the query.
- Use a command to update all the selected issues and assign them the same value in the new enumerated custom field. For example: Secondary State Submitted. To minimize notification spam, apply the commands without sending notifications.
- Repeat this step until you have added all the values that were stored in the state-type custom field to the new enumerated custom field.
Return to the Administration > Custom Fields page and remove the extra state-type custom field from the project.
- The field and its related values are deleted from the project.
- All the values that were previously stored in this custom field are now stored in the enumerated custom field.
Repeat this procedure until you have replaced all the extra state-type fields in the project.

Last modified: 12 June 2024