---
schema: rendered-html/v1
title: "UserProjectCustomField | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/v1-UserProjectCustomField.html
generated_at: 2026-06-11T15:20:10.511574+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- JavaScript Workflow Quick Start Guide
- Create a Workflow
- Edit a Workflow
- Workflow Rule Types
- Transactions
- Use Cases for Workflows
- Web-based Workflow Editor
- Using an External Code Editor
- Default Workflows
- Custom Workflow Repository
- JavaScript Workflow Reference
- Rule-specific Properties
- Context
- Requirements
- Using the Workflow API
- Building Integrations with Slack
- Using REST API Methods in JavaScript Workflows
- Working with Dates and Times
- Working with Periods
- Localized Workflow Messages
- Troubleshooting Workflows
- Remote Debugger
- YouTrack Workflow API
- Change Log
- [date-time](jetbrains__com__help__youtrack__devportal__v1-date-time.md)
- [entities](jetbrains__com__help__youtrack__devportal__v1-entities.md)
- AbstractVcsItem
- Agile
- AppGlobalStorage
- Article
- ArticleAttachment
- ArticleComment
- BaseArticle
- BaseArticleAttachment
- BaseArticleComment
- BaseComment
- BaseEntity
- BaseWorkItem
- Build
- BundleElementCondition
- BundleProjectCustomField
- Calendar
- Calendar24x7
- ChangesProcessor
- Channel
- EnumField
- FeedbackForm
- Field
- FieldBasedBundleValuesCondition
- FieldBasedUserValuesCondition
- FieldBasedValuesCondition
- Fields
- Gantt
- GroupProjectCustomField
- Issue
- IssueAttachment
- IssueComment
- IssueLinkPrototype
- IssueTag
- IssueWorkItem
- Iterator
- JsonForArticleAddAttachment
- JsonForArticleAddComment
- JsonForArticleConstructor
- JsonForIssueAddAttachment
- JsonForIssueAddComment
- JsonForIssueAddWorkItem
- JsonForIssueCommentAddAttachment
- JsonForIssueConstructor
- JsonForUserNotify
- MailboxChannel
- OwnedField
- PeriodProjectCustomField
- PersistentFile
- Project
- ProjectCustomField
- ProjectTeam
- ProjectType
- ProjectVersion
- PullRequest
- PullRequestState
- Requirement
- Requirements
- SavedQuery
- Set
- SimpleCalendar
- SimpleProjectCustomField
- Sprint
- State
- Tag
- TextProjectCustomField
- User
- UserAttributes
- UserCondition
- [UserGroup](jetbrains__com__help__youtrack__devportal__v1-usergroup.md)
- [UserProjectCustomField](v1-UserProjectCustomField.html)
- [UserType](jetbrains__com__help__youtrack__devportal__v1-usertype.md)
- [VcsChange](jetbrains__com__help__youtrack__devportal__v1-vcschange.md)
- [VcsServer](jetbrains__com__help__youtrack__devportal__v1-vcsserver.md)
- [WatchFolder](jetbrains__com__help__youtrack__devportal__v1-watchfolder.md)
- [WorkItemAttributeValue](jetbrains__com__help__youtrack__devportal__v1-workitemattributevalue.md)
- [WorkItemAttributes](jetbrains__com__help__youtrack__devportal__v1-workitemattributes.md)
- [WorkItemProjectAttribute](jetbrains__com__help__youtrack__devportal__v1-workitemprojectattribute.md)
- [WorkItemType](jetbrains__com__help__youtrack__devportal__v1-workitemtype.md)
- http
- license
- notifications
- search
- strings
- workflow
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Hub REST API

1. YouTrack Workflows
2. JavaScript Workflow Reference
3. YouTrack Workflow API
4. [entities](jetbrains__com__help__youtrack__devportal__v1-entities.md)
5. [UserProjectCustomField](#0)

# UserProjectCustomField﻿

Last modified: 07 May 2026

Represents a custom field in a project that stores values as a user type.

Extends ProjectCustomField.

## Properties﻿

| --- | --- | --- |
| becomesRemoved | Boolean | Read-only.   When `true`, the entity is removed in the current transaction. Otherwise, `false`. This property can become `true` only in on-change rules when the rule is triggered on the removal of an issue or an article. In the rule code, the `runOn` rule property must contain the `removal` parameter set to `true`.    Available since 2017.4.37915  ``` runOn: {removal: true} ``` |
| defaultUsers | Set.<User> | Read-only.   The default value for the custom field. |
| extensionProperties | Object | The object containing extension properties for this entity and their values. Extension properties are custom properties that might be added to core YouTrack entities by an app. For details about extension properties, see <https://www.jetbrains.com/help/youtrack/devportal/apps-extension-properties.html>.    Available since 2024.3  ``` const entities = require('@jetbrains/youtrack-scripting-api/entities');  exports.rule = entities.Issue.action({     command: 'test',     action: function (ctx) {         const printValues = () => {             return 'stringProp:' + ctx.issue.extensionProperties.stringProp + ';'                 + 'integerProp:' + ctx.issue.extensionProperties.integerProp + ';'                 + 'booleanProp:' + ctx.issue.extensionProperties.booleanProp + ';'                 + 'issueProp:' + ctx.issue.extensionProperties.issueProp?.id + ';'                 + 'issuesProp:' + ctx.issue.extensionProperties.issuesProp?.first()?.id + ';'         }         ctx.issue.addComment(printValues());     } }); ``` |
| isNew | Boolean | Read-only.   When `true`, the entity is created in the current transaction. Otherwise, `false`.    Available since 2018.2.42351 |
| localizedName | String | Read-only.   The localized name of the field. |
| name | String | Read-only.   The name of the field. |
| nullValueText | String | Read-only.   The text that is displayed for this field when it is empty. |
| typeName | String | Read-only.   The data type assigned to values stored in the custom field. |
| values | Set.<User> | Read-only.   The list of available values for the custom field. |
| valuesCondition | FieldBasedUserValuesCondition | Read-only.   The condition that determines which values are possible for this field based on the condition field value. If not set, all values are possible.    Available since 2025.3 |

## Methods﻿

### findByExtensionProperties﻿

```
static findByExtensionProperties(extensionPropertiesQuery)
```

Searches for UserProjectCustomField entities with extension properties that match the specified query.

Available since 2024.3.43260

**Parameters**

| --- | --- | --- |
| extensionPropertiesQuery | Object | The extension properties query, defined as a set of key-value pairs representing properties and their corresponding values. |

**Return Value**

| Type | Description |
| Set.<UserProjectCustomField> | The set of UserProjectCustomField entities that contain the specified extension properties. |

**Example**

```
{
   property1: "value1",
   property2: "value2"
}
```

### becomes﻿

```
becomes(fieldName, expected)
```

Checks whether a field is set to an expected value in the current transaction.

**Parameters**

| --- | --- | --- |
| fieldName | string | The name of the field to check. |
| expected | string | The expected value. |

**Return Value**

| Type | Description |
| boolean | If the field is set to the expected value, returns `true`. |

### becomesInvisibleInIssue﻿

```
becomesInvisibleInIssue(issue)
```

Checks if the changes that are applied in the current transaction remove the condition to show the custom field.

Available since 2018.2.42312

**Parameters**

| --- | --- | --- |
| issue | Issue | The issue for which the condition for showing the field is checked. |

**Return Value**

| Type | Description |
| Boolean | When `true`, the condition for showing the field is removed in the current transaction. |

### becomesVisibleInIssue﻿

```
becomesVisibleInIssue(issue)
```

Checks if the changes that are applied in the current transaction satisfy the condition to show the custom field.

Available since 2018.2.42312

**Parameters**

| --- | --- | --- |
| issue | Issue | The issue for which the condition for showing the field is checked. |

**Return Value**

| Type | Description |
| Boolean | When `true`, the condition for showing the field is met in the current transaction. |

### canBeReadBy﻿

```
canBeReadBy(fieldName, user)
```

Checks whether a user has permission to read the field.

**Parameters**

| --- | --- | --- |
| fieldName | string | The name of the field. |
| user | User | The user for whom the permission to read the field is checked. |

**Return Value**

| Type | Description |
| boolean | If the user can read the field, returns `true`. |

### canBeWrittenBy﻿

```
canBeWrittenBy(fieldName, user)
```

Checks whether a user has permission to update the field.

**Parameters**

| --- | --- | --- |
| fieldName | string | The name of the field. |
| user | User | The user for whom the permission to update the field is checked. |

**Return Value**

| Type | Description |
| boolean | If the user can update the field, returns `true`. |

### findValueByLogin﻿

```
findValueByLogin(login)
```

Returns the value that matches the specified login in a custom field that stores values as a user type.

**Parameters**

| --- | --- | --- |
| login | String | The user login to search for in the set of values for the custom field. |

**Return Value**

| Type | Description |
| User | The user with the specified login. This user can be set as the value for a field that stores a user type. |

### getBackgroundColor﻿

```
getBackgroundColor(issue)
```

Returns the background color that is used for this field value in the specified issue. Can return `null`, `"white"`, or a hex color presentation.

**Parameters**

| --- | --- | --- |
| issue | Issue | The issue for which the background color is returned. |

**Return Value**

| Type | Description |
| String | The background color that is used for this field value in the specified issue. |

### getForegroundColor﻿

```
getForegroundColor(issue)
```

Returns the foreground color that is used for this field value in the specified issue. Can return `null`, `"white"`, or a hex color presentation.

**Parameters**

| --- | --- | --- |
| issue | Issue | The issue for which the foreground color is returned. |

**Return Value**

| Type | Description |
| String | The foreground color that is used for this field value in the specified issue. |

### getPossibleValuesForIssue﻿

```
getPossibleValuesForIssue(issue)
```

The list of possible custom field values based on the value-based conditions in the project settings and the current value stored in the issue. If there are no value-based conditions in the project settings, returns the complete list of values for the custom field.

Available since 2025.3

**Parameters**

| --- | --- | --- |
| issue | Issue | The issue for which the value is checked. |

**Return Value**

| Type | Description |
| Set.<User> | The set of possible users. |

### getValuePresentation﻿

```
getValuePresentation(issue)
```

Returns the string presentation of the value that is stored in this field in the specified issue.

**Parameters**

| --- | --- | --- |
| issue | Issue | The issue for which the value presentation is returned. |

**Return Value**

| Type | Description |
| String | The string presentation of the value. |

### is﻿

```
is(fieldName, expected)
```

Checks whether a field is equal to an expected value.

Available since 2019.2.55603

**Parameters**

| --- | --- | --- |
| fieldName | string | The name of the field to check. |
| expected | string | The expected value. |

**Return Value**

| Type | Description |
| boolean | If the field is equal to the expected value, returns `true`. |

### isChanged﻿

```
isChanged(fieldName)
```

Checks whether the value of a field is changed in the current transaction.

**Parameters**

| --- | --- | --- |
| fieldName | string | The name of the field to check. |

**Return Value**

| Type | Description |
| boolean | If the value of the field is changed in the current transaction, returns `true`. |

### isValuePermittedInIssue﻿

```
isValuePermittedInIssue(issue, value)
```

Checks if value is permitted in the issue.

Available since 2025.2

**Parameters**

| --- | --- | --- |
| issue | Issue | The issue for which the value is checked. |
| value | User | The value to check. |

**Return Value**

| Type | Description |
| Boolean | If the value can be used for the issue, returns `true`. |

### isVisibleInIssue﻿

```
isVisibleInIssue(issue)
```

Checks if a field is visible in the issue.

Available since 2018.2.42312

**Parameters**

| --- | --- | --- |
| issue | Issue | The issue for which the condition for showing the field is checked. |

**Return Value**

| Type | Description |
| Boolean | When `true`, the condition for showing the custom field in the issue has been met. It can also mean that the field is not shown on a conditional basis and is always visible. |

**Example**

```
// The following example checks the issue to see whether a conditional field with the name "Related Activity"
// is currently visible, meaning that the conditions for showing the field have been met.
// If so, the value for the field is set to "Attendance"

action: function (ctx) {
  if (ctx.RelatedActivity.isVisibleInIssue(ctx.issue)) {
    ctx.issue.fields.RelatedActivity.add(ctx.RelatedActivity.Attendance);
  }
},
requirements: {
  RelatedActivity: {
    name: 'Related Activity',
    type: entities.EnumField.fieldType,
    multi: true,
    Attendance: {}
  }
}
```

### oldValue﻿

```
oldValue(fieldName)
```

Returns the previous value of a single-value field before an update was applied. If the field is not changed in the transaction, returns null.

**Parameters**

| --- | --- | --- |
| fieldName | string | The name of the field. |

**Return Value**

| Type | Description |
| Object | If the field is changed in the current transaction, the previous value of the field. Otherwise, null. |

### required﻿

```
required(fieldName, message)
```

Asserts that a value is set for a field. If a value for the required field is not set, the specified message is displayed in the user interface.

**Parameters**

| --- | --- | --- |
| fieldName | string | The name of the field to check. |
| message | string | The message that is displayed to the user that describes the field requirement. |

### was﻿

```
was(fieldName, expected)
```

Checks whether a field was equal to an expected value prior to the current transaction.

Available since 2019.2.55603

**Parameters**

| --- | --- | --- |
| fieldName | string | The name of the field to check. |
| expected | string | The expected value. |

**Return Value**

| Type | Description |
| boolean | If the field was equal to the expected value, returns `true`. |

- [UserProjectCustomField](/help/youtrack/devportal/v1-UserProjectCustomField.html)
- [Properties](/help/youtrack/devportal/v1-UserProjectCustomField.html#properties)
- [Methods](/help/youtrack/devportal/v1-UserProjectCustomField.html#methods)
- [findByExtensionProperties](/help/youtrack/devportal/v1-UserProjectCustomField.html#findByExtensionProperties)
- [becomes](/help/youtrack/devportal/v1-UserProjectCustomField.html#becomes)
- [becomesInvisibleInIssue](/help/youtrack/devportal/v1-UserProjectCustomField.html#becomesInvisibleInIssue)
- [becomesVisibleInIssue](/help/youtrack/devportal/v1-UserProjectCustomField.html#becomesVisibleInIssue)
- [canBeReadBy](/help/youtrack/devportal/v1-UserProjectCustomField.html#canBeReadBy)
- [canBeWrittenBy](/help/youtrack/devportal/v1-UserProjectCustomField.html#canBeWrittenBy)
- [findValueByLogin](/help/youtrack/devportal/v1-UserProjectCustomField.html#findValueByLogin)
- [getBackgroundColor](/help/youtrack/devportal/v1-UserProjectCustomField.html#getBackgroundColor)
- [getForegroundColor](/help/youtrack/devportal/v1-UserProjectCustomField.html#getForegroundColor)
- [getPossibleValuesForIssue](/help/youtrack/devportal/v1-UserProjectCustomField.html#getPossibleValuesForIssue)
- [getValuePresentation](/help/youtrack/devportal/v1-UserProjectCustomField.html#getValuePresentation)
- [is](/help/youtrack/devportal/v1-UserProjectCustomField.html#is)
- [isChanged](/help/youtrack/devportal/v1-UserProjectCustomField.html#isChanged)
- [isValuePermittedInIssue](/help/youtrack/devportal/v1-UserProjectCustomField.html#isValuePermittedInIssue)
- [isVisibleInIssue](/help/youtrack/devportal/v1-UserProjectCustomField.html#isVisibleInIssue)
- [oldValue](/help/youtrack/devportal/v1-UserProjectCustomField.html#oldValue)
- [required](/help/youtrack/devportal/v1-UserProjectCustomField.html#required)
- [was](/help/youtrack/devportal/v1-UserProjectCustomField.html#was)

[UserGroup](jetbrains__com__help__youtrack__devportal__v1-usergroup.md)[UserType](jetbrains__com__help__youtrack__devportal__v1-usertype.md)

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
