YouTrack Server
 
2019.2
Get YouTrack Standalone
You are viewing the documentation for an earlier version of YouTrack Server. View this page in the current documentation
  1. Administration
  2. Custom Fields
  3. Custom Field Types

Custom Field Types

Last modified: 17 December 2019

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.

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 then 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 user login. 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 that 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 of 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 replace extra state-type fields with fields that use a generic enumerated type. This makes the resolved state dependent on the values for a single custom field.

    Unfortunately, you can only use the Replace function with custom fields that share the same data type. Use the following procedure to create new enumerated custom fields and remove extra state-type fields from your projects.

To replace extra state-type fields:

  1. Open the Administration > Custom Fields page.

  2. Locate the project that contains extra state-type custom fields.

  3. Click the Add field to project button.

  4. Use the settings to define a custom field that stores an enum type.

  5. Add the same values to the new custom field that are used in one of the extra state-type custom fields.

  6. 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 of 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 of the issues that are returned by the search query. Use the keyboard shortcut Ctrl + A (⌘ + A on macOS) to select all of the issues that are returned by the query.

    • Use a command to update all of 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 silently.

    • Repeat this step until you have added all of the values that were stored in the state-type custom field to the new enumerated custom field.

  7. 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 of the values that were previously stored in this custom field are now stored in the enumerated custom field.

  8. Repeat this procedure until you have replaced all of the extra state-type fields in the project.