YouTrack Standalone 7.0 Help

Manage Custom Fields

On this page:

As a project administrator, you can customize the fields that are used for issues in your projects. System administrators can modify the properties of custom fields for all projects in the system. For more information, see Custom Fields.

To access and manage the fields that are used for issues in your project, select the Fields tab in the Edit Project page.

Add a New Field

As the project administrator, you can add new fields for the issues in your project.

When you add a field to your project, the custom field is available to other projects in the system. A system administrator or user with global project administration permissions can reuse this field in other projects. For enumerated custom fields, the set of available values is managed for each project independently.

When you create a custom field, be sure to set the field type that you want to assign to values that are stored in the field. This setting cannot be changed later. Converting values from one data type to another is a manual process that takes time and effort. For more information, see Change Field Type.

To add a field:

  1. From the Edit Project page, select the Fields tab.
  2. Click the Add field to project button.
    • The New Custom Field dialog opens in the sidebar.
      newCustomFieldInProject
  3. Enter values in the custom field settings. For a detailed description of each setting, see Manage Custom Fields.
  4. If the field is an enumerated type, you have the following options:
    • Select the New set option. Define the set of values after you create the custom field.
    • Select a field from the list. The set of values that is used in the select field is added to the new field.
  5. Click the Add new field button.
    • The custom field is added to your project.

Attach a Custom Field to Your Project

If you want to use an exiting field for issues in your project, you can attach it to your project.

To attach a field to your project:

  1. From the Edit Project page, select the Fields tab.
  2. Click the Add field to project button.
    • The Add field to project dialog opens in the sidebar.
  3. Select the Use existing tab.
    attachFieldProjectEdit
  4. Select the field you want to attach to the project. Use the search box to filter the list of custom fields.
  5. Click the + icon next to the field name to attach it to the project.
    • The settings for the selected field are displayed in the sidebar.
    • If the field is used in other projects, you can only modify the settings for the custom field when you have the Update Project permission for all of the projects that use the field.
      attachFieldNoPermissions

      If the current field settings are compatible with your project, you can use the field without making any changes.

  6. If you want to customize the settings for the field, click the Make independent copy button.
    • A copy of the custom field and its current settings is created in your project. For a detailed description of each setting, see Manage Custom Fields.
    • You can freely edit settings and values without affecting the settings for this field in other projects.

Change Field Order at the Project Level

The default order in which fields are displayed on Issues list and full page view is set at the global level by an administrator. If you prefer to order the fields differently, you can set a custom order for your project. Project-level settings override the global settings.

To change the field order:

  1. From the Edit Project page, select the Fields tab.
  2. Set the order of custom fields by dragging them into the desired sequence.
    changeFieldOrderProject

Edit a Set of Values

You can edit the set of values that are used in a field.

Wherever you can change the value for a field, there is an option to add a new value to the set. As a project administrator, you can add values to fields that are unique to your project or use an independent set of values. System administrators and users with project administrator access in the global project can add values to the set in all projects. When created, the new value is added to the issue. This option is visible in the following locations:

  • Issues list
  • Full page view
  • Agile boards
add-value-to-field

If the set of values is shared with other projects, you can make an independent copy of the set and edit the values for the field in your project.

To edit a set of values that is shared with other projects:

  1. From the Edit Project page, select the Fields tab.
  2. Select the field that uses the set of values.
    • The details dialog for the selected custom field opens in the sidebar.
  3. Click the Make independent copy button.
    editSetOfValuesInProject
  4. Edit the set of values. The following options are available:
    • Click the Add value button to add a new value to the list.
    • Click the Copy values from button and select a field to copy the values used in the selected field. The values from the selected field are added to the current set of values.
    • Click the Merge with button and select a field to merge existing values with the values used in the selected field. The values from the selected field are merged with the current set of values.

Replace a Custom Field

You can replace the custom fields that are used in your project with a custom field that is used in other projects. Use this feature if there are custom fields that are used in other projects that you want to use instead of the custom field that is set in your project. You can then use the same custom field, for example, to generate reports or display the same columns and swimlanes for all of the projects on an agile board.

Unfortunately, you can only use the Replace function with custom fields that share the same data type. To convert values from one data type to another, you need to create a new custom field with the desired type and manually update the values in the new field for all issues in the project. For more information, see Change Field Type.

To replace a custom field:

  1. From the Edit Project page, select the Fields tab.
  2. Select the field that you want to replace and click the Replace button.
    • A drop-down list shows all available custom fields that store the same data type.
      replaceCustomField
  3. Select the custom field that you want to replace the existing field.
    • The custom field is replaced with the selected custom field in the project.
    • The set of values that was used by the previous custom field is added to the set of values for the replacement field in the project.
    • The values in the original custom field that are assigned to issues in the project are updated to use the same values in the replacement field.
    • The sets of values that are used in other projects for the replacement field remain unchanged.

Change Field Type

If you want to replace an existing custom field with a field that uses a different type, you can't use the Replace function. Instead, you need to add a custom field to the project that stores values in the desired type and migrate the data manually from the original field.

To migrate data from one custom field to another custom field:

  1. From the Edit Project page, select the Fields tab.
  2. Click the Add field to project button.
  3. Use the settings to define a custom field or select an existing field that stores values in the desired type.
  4. If the new custom field stores enumerated values, add values to the new custom field that are used in the existing custom field.
  5. 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 original custom field. For enumerated types, 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 OS X) 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 a value in the new custom field. For example: Secondary State Submitted. To minimize notification spam, apply the commands silently.
    • Repeat this step until you have migrated all of the data that was stored in the original custom field to the new custom field.
  6. Return to the Administration > Custom Fields page and remove the original 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 the original custom field are now stored in the new custom field.

Custom Field Settings

The following settings are used for fields with simple data types:

FieldDescription
Field NameEnter a name for the custom field.
TypeSelect the field type. When you select a type, additional parameters that are used to define the selected type are displayed.
AliasesEnter one ore more values to use as keywords in search queries. For example, for a field 'Project' the alias can be 'in:', so you can use in: MyProject as a search query instead of project: MyProject.
Can be emptySelect if the field can have an empty value. For fields with simple types, this option is always enabled.
Empty value nameEnter the value to show by default in the empty field.
Make privateSelect to make the field visible only to users with permission to view private fields.

The following additional settings are available for fields with enumerated data types:

FieldDescription
Multi-valueSelect to allow one or more values to be stored in the field.
Set of ValuesSelect the default set of values to store in the custom field.
  • New set — Attaches a new list of values to the field.
  • Existing set — Attaches an existing list of values to the field. When you select an existing set of values, you can set the default value to use for this field.
Default Value(s)When you select an existing set of values, you have the option to set the default value that is assigned to the field. If the Multi-value setting is enabled, you can select one or more default values.
Can be emptySelect if the field can have an empty value. You can only disable this option when a default value has been set.
Empty value nameEnter the text to display in the issue field when the field is empty.
Last modified: 25 October 2016