Issue
Represents an issue in YouTrack.
Extends BaseEntity.
Properties
Name | Type | Description |
---|---|---|
attachments | Set.<IssueAttachment> | Read-only. The set of attachments that are attached to the issue. |
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} |
becomesReported | Boolean | Read-only. If the issue becomes reported in the current transaction, this property is `true`. if (issue.fields.Subsystem !== null && issue.fields.Assignee === null &&
(((issue.isChanged('Subsystem') || issue.isChanged('project') && issue.isReported) ||
issue.becomesReported) {
issue.fields.Assignee = issue.fields.Subsystem.owner
} |
becomesResolved | Boolean | Read-only. If the issue is assigned a state that is considered resolved in the current transaction, this property is `true`. |
becomesUnresolved | Boolean | Read-only. If the issue is assigned a state that is considered unresolved in the current transaction. this property is `true`. |
channel | Channel | Read-only. The channel used by the reporter to create the ticket. Possible values are 'FeedbackForm' for online forms or 'MailboxChannel' for email. |
comments | Set.<IssueComment> | Read-only. A list of comments for the issue. |
created | Number | Read-only. The date when the issue was created. |
description | String | The text that is entered as the issue description. |
duplicateRoot | Issue | Read-only. The root issue in a tree of duplicates that are linked to the issue. For example, if `issueA` duplicates `issueB` and `issueB` duplicates `issueC`, then the value for the `issueA.duplicateRoot()` property is `issueC`. |
editedComments | Set.<IssueComment> | Read-only. The set of comments that are edited in the current transaction. Comments that are added and removed are not considered to be edited. Instead, these are represented by the `issue.comments.added` and `issue.comments.removed` properties. |
editedWorkItems | Set.<IssueWorkItem> | Read-only. The set of work items that are edited in the current transaction. Work items that are added and removed are not considered to be edited. Instead, these are represented by the `issue.workItems.added` and `issue.workItems.removed` properties. Available since 2017.4.37824 |
fields | Fields | The custom fields that are used in an issue. This is the collection of issue attributes like `Assignee`, `State`, and `Priority` that are defined in the Custom Fields section of the administrative interface and can be attached to each project independently. Issue attributes like `reporter`, `numberInProject`, and `project` are accessed directly. if (issue.fields.becomes(ctx.Priority, ctx.Priority.Critical) {
issue.fields.Assignee = issue.project.leader;
} |
id | String | Read-only. The issue ID. user.notify('Issue is overdue', 'Please, look at the issue: ' + issue.id); |
isNew | Boolean | Read-only. When `true`, the entity is created in the current transaction. Otherwise, `false`. Available since 2018.2.42351 |
isReported | Boolean | Read-only. If the issue is already reported or becomes reported in the current transaction, this property is `true`. To apply changes to an issue draft, use `!issue.isReported`. issue.links['depends on'].forEach(function(dep) {
if (dep.isReported) {
assert(dep.State.resolved, 'The issue has unresolved dependencies and thus cannot be set Fixed!');
}
}); |
isResolved | Boolean | Read-only. If the issue is currently assigned a state that is considered resolved, this property is `true`. |
isStarred | Boolean | Read-only. If the current user has added the 'Star' tag to watch the issue, this property is `true`. |
links | Object | Issue links (e.g. `relates to`, `parent for`, etc.). Each link is a Set of Issue objects. if (issue.links['parent for'].added.isNotEmpty()) {
issue.links['parent for'].added.forEach(function(subtask) {
subtask.fields.Priority = issue.fields.Priority;
});
} |
numberInProject | Number | Read-only. The issue number in the project. |
permittedGroup | UserGroup | The user group for which the issue is visible. If the property contains a null value, the issue is visible to the All Users group. |
permittedGroups | Set.<UserGroup> | The groups for which the issue is visible when the visibility is restricted to multiple groups. |
permittedUsers | Set.<User> | The list of users for whom the issue is visible. |
pinnedComments | Set.<IssueComment> | Read-only. The set of comments that are pinned in the issue. Available since 2024.1 |
project | Project | The project to which the issue is assigned. |
pullRequests | Set.<PullRequest> | Read-only. The list of pull requests that are associated with the issue. Available since 2020.3 |
reporter | User | Read-only. The user who reported (created) the issue. issue.fields.Assignee = issue.reporter; |
resolved | Number | Read-only. The date and time when the issue was assigned a state that is considered to be resolved. |
summary | String | The text that is entered as the issue summary. |
tags | Set.<Tag> | The list of tags that are attached to an issue. |
unauthenticatedReporter | Boolean | Read-only. When true, the ticket was created by a reporter who was not logged in to YouTrack when they submitted the support request. |
updated | Number | Read-only. The date when the issue was last updated. |
updatedBy | User | Read-only. The user who last updated the issue. |
url | String | Read-only. The absolute URL that points to the issue. user.notify('Issue is overdue', 'Please, look at the issue: ' + issue.url); |
vcsChanges | Set.<VcsChange> | Read-only. The list of commits that are associated with the issue. Available since 2018.1.38923 |
voters | Set.<User> | Read-only. Users who voted for the issue. Available since 2020.5 |
votes | Number | Read-only. The number of votes for an issue. For vote-related methods, see User.canVoteIssue, User.voteIssue, User.canUnvoteIssue, and User.unvoteIssue. |
workItems | Set.<IssueWorkItem> | Read-only. The set of work items that have been added to the issue. |
Constructors
Issue
Parameters
Name | Type | Description |
---|---|---|
reporter | User, JsonForIssueConstructor | Issue reporter. Alternatively, pass a JSON specified by JsonForIssueConstructor |
project | Project | Project that the new issue is to belong to. |
summary | String | Issue summary. |
Methods
action
Creates a declaration of a rule that a user can apply to one or more issues with a command or menu option. The object that is returned by this method is normally exported to the `rule` property, otherwise it is not treated as a rule.
Parameters
Name | Type | Description |
---|---|---|
ruleProperties | Object | A JSON object that defines the properties for the rule. |
ruleProperties.title | string | The human-readable name of the rule. Displayed in the administrative UI in YouTrack. |
ruleProperties.command | string | The custom command that triggers the action. |
ruleProperties.userInput | Object | An object that defines the properties for information that will be requested from the user who triggers the action rule. |
ruleProperties.userInput.type | string, Object | The data type for the value that is requested from the user. The following types are supported: * entities.Field.dateTimeType * entities.Field.dateType * entities.Field.integerType * entities.Field.floatType * entities.Field.periodType * entities.Field.stringType * entities.Build * entities.EnumField * entities.Issue * entities.IssueTag * entities.OwnedField * entities.Project * entities.ProjectVersion * entities.UserGroup * entities.User |
ruleProperties.userInput.description | string | The label for the control that is used to collect additional information from the user. |
ruleProperties.guard | Issue~guardFunction | A function that is invoked to determine whether the action is applicable to an issue. |
ruleProperties.action | Issue~actionFunction | The function that is invoked when a user triggers this action. |
ruleProperties.requirements | Requirements | The set of entities that must be present for the script to work as expected. |
Return Value
Type | Description |
---|---|
Object | The object representation of the rule. |
Example
findByExtensionProperties
Searches Issue by the extension properties query.
Available since 2024.3.43260
Parameters
Name | Type | Description |
---|---|---|
extensionPropertiesQuery | Object | The extension properties query. |
Return Value
Type | Description |
---|---|
Set.<Issue> | The set of Issue entities found by the extension properties query. |
Example
findById
Finds an issue by its visible ID.
Parameters
Name | Type | Description |
---|---|---|
id | String | The issue ID. |
Return Value
Type | Description |
---|---|
Issue | The issue that is assigned the specified ID. |
Example
onChange
Creates a declaration of a rule that is triggered when a change is applied to an issue. The object that is returned by this method is normally exported to the `rule` property, otherwise it is not treated as a rule.
Parameters
Name | Type | Description |
---|---|---|
ruleProperties | Object | A JSON object that defines the properties for the rule. |
ruleProperties.title | string | The human-readable name of the rule. Displayed in the administrative UI in YouTrack. |
ruleProperties.guard | Issue~guardFunction | A function that determines the conditions for executing the rule. If the guard condition is not met, the action specified in the rule is not applied to the issue. |
ruleProperties.action | Issue~actionFunction | The function that is invoked on an issue change. |
ruleProperties.requirements | Requirements | The set of entities that must be present for the script to work as expected. |
ruleProperties.runOn | Object | Determines which issue events trigger the on-change rule. When not specified, the rule is triggered on an issue change. |
ruleProperties.runOn.change | boolean | When `true`, the rule is triggered on an issue change. |
ruleProperties.runOn.removal | boolean | When `true`, the rule is triggered when an issue is logically deleted. |
Return Value
Type | Description |
---|---|
Object | The object representation of the rule. |
Example
onSchedule
Creates a declaration of a rule that is triggered on a set schedule. The object that is returned by this method is normally exported to the `rule` property, otherwise it is not treated as a rule.
Parameters
Name | Type | Description |
---|---|---|
ruleProperties | Object | A JSON object that defines the properties for the rule. |
ruleProperties.title | string | The human-readable name of the rule. Displayed in the administrative UI in YouTrack. |
ruleProperties.search | string, function | A YouTrack search string or a function with no parameters that returns such a string. The specified action is applied to all issues that match the search and belong to the project that this rule is attached to. |
ruleProperties.cron | string | A cron expression that specifies the interval for applying the rule. |
ruleProperties.muteUpdateNotifications | boolean | `true` if no notifications should be sent on changes made by this rule or any rule that reacted on a change made by this rule. |
ruleProperties.modifyUpdatedProperties | boolean | When `true`, updates applied by the workflow rule are reflected in the `updated` and `updatedBy` properties of the target entity. Otherwise, the values for these properties remain unchanged. |
ruleProperties.action | Issue~actionFunction | The function that is invoked on schedule for each issue that matches the search. |
ruleProperties.requirements | Requirements | The set of entities that must be present for the script to work as expected. |
Return Value
Type | Description |
---|---|
Object | The object representation of the rule. |
Example
sla
Creates a declaration of a custom SLA policy. An SLA policy defines the time goals for the replies from staff and request resolution.
Parameters
Name | Type | Description |
---|---|---|
ruleProperties | Object | A JSON object that defines the properties for the SLA policy. |
ruleProperties.title | string | The human-readable name of the SLA policy. Displayed in the administrative UI in YouTrack. |
ruleProperties.guard | Issue~slaGuardFunction | A function that is invoked to determine whether the policy is applicable to the ticket. |
ruleProperties.onEnter | Issue~slaEnterFunction | A function that is invoked when the SLA policy starts applying to the ticket. |
ruleProperties.action | Issue~slaActionFunction | The function that is invoked when the policy needs to update the ticket. For example, it might pause the timers according to the SLA settings. |
ruleProperties.onBreach | Issue~slaBreachFunction | A function that is invoked when one of the SLA goals is breached. The name of the field that caused the breach is stored in the ctx.breachedField parameter. |
ruleProperties.requirements | Requirements | The set of entities that must be present for the script to work as expected. When you define a custom field of date and time type in the requirements, YouTrack handles this field as an SLA timer. |
Return Value
Type | Description |
---|---|
Object | The object representation of the SLA policy. |
Example
stateMachine
Creates a declaration of a state-machine rule. The state-machine imposes restrictions for the transitions between values in a custom field. You can execute actions when the custom field is set to a value, changes from a value, or transitions from two specific values. The object that is returned by this method is normally exported to the `rule` property, otherwise it is not treated as a rule.
Parameters
Name | Type | Description |
---|---|---|
ruleProperties | Object | A JSON object that defines the properties for the rule. |
ruleProperties.title | string | The human-readable name of the rule. Displayed in the administrative UI in YouTrack. |
ruleProperties.fieldName | string | The name of a field that is managed by the state-machine rule. Declare either fieldName or stateFieldName, not both. |
ruleProperties.stateFieldName | string | An alias for ruleProperties.fieldName for building state-machines per issue type. When both stateFieldName and fieldName are declared, an exception is thrown. |
ruleProperties.states | Object | A list of values for a custom field and the possible transitions between them. Declare either states or defaultStateMachine, not both. |
ruleProperties.defaultMachine | Object | An alias for ruleProperties.states for building state-machines per issue type. When both defaultMachine and states are declared, an exception is thrown. |
ruleProperties.typeFieldName | string | The name of a field that defines which state-machine applies to the managed field. |
ruleProperties.alternativeMachines | Object | An object that contains the definitions for one or more state-machines that apply to different types of issues. Object keys are the possible values of the field that is defined by the ruleProperties.typeFieldName. Object values have the same structure that is shown for 'states' in the example. This parameter is mandatory when the ruleProperties.typeFieldName parameter is specified. |
ruleProperties.requirements | Requirements | The set of entities that must be present for the script to work as expected. |
Return Value
Type | Description |
---|---|
Object | The object representation of the rule. |
Example
addAttachment
Attaches a file to the issue. Makes `issue.attachments.isChanged` return `true` for the current transaction.
Available since 2019.2.53994
Parameters
Name | Type | Description |
---|---|---|
content | InputStream, String, JsonForIssueAddAttachment | The content of the file in binary or base64 form. Alternatively, pass a JSON specified by JsonForIssueAddAttachment |
name | String | The name of the file. |
charset | String | The charset of the file. Only applicable to text files. |
mimeType | String | The MIME type of the file. |
Return Value
Type | Description |
---|---|
IssueAttachment | The attachment that is added to the issue. |
addComment
Adds a comment to the issue. Makes `issue.comments.isChanged` return `true` for the current transaction.
Parameters
Name | Type | Description |
---|---|---|
text | String, JsonForIssueAddComment | The text to add to the issue as a comment. Alternatively, pass a JSON specified by JsonForIssueAddComment |
author | User | The author of the comment. |
Return Value
Type | Description |
---|---|
IssueComment | A newly created comment. |
addTag
Adds a tag with the specified name to an issue. YouTrack adds the first matching tag that is visible to the current user. If a match is not found, a new private tag is created for the current user. When you use this method to add the star tag to an issue, the current user is added to the list of watchers. To add a tag that is not visible to the current user, use the `applyCommand` method instead. Use "add tag [tagName]" for the command parameter and specify the login for the owner of the tag in the `runAs` parameter.
Parameters
Name | Type | Description |
---|---|---|
name | String | The name of the tag to add to the issue. |
Return Value
Type | Description |
---|---|
Tag | The tag that has been added to the issue. |
Example
addWorkItem
Adds a work item to the issue.
Parameters
Name | Type | Description |
---|---|---|
description | String, JsonForIssueAddWorkItem | The description of the work item. Alternatively, pass a JSON specified by JsonForIssueAddWorkItem |
date | Number | The date that is assigned to the work item. |
author | User | The user who performed the work. |
duration | Number | The work duration in minutes. |
type | WorkItemType | The work item type. |
Return Value
Type | Description |
---|---|
IssueWorkItem | The new work item. |
afterMinutes
Adds the specified number of minutes to a specified starting point in time.
Available since 2023.1
Parameters
Name | Type | Description |
---|---|---|
initialTime | Number | A timestamp for the starting point in time. YouTrack adds the specified number of minutes to this point. |
minutes | Number | The number of minutes to add to the starting point. |
calendar | Calendar | The SLA settings for the business hours that should be considered when adding minutes to the starting point. If the result falls outside the business hours after adding specified minutes, the extra minutes get automatically transferred to the next business day. |
considerPauses | Boolean | A switcher that determines whether to consider the effects of the 'pauseSLA' and 'resumeSLA' methods when adding specified minutes to the starting point. |
Return Value
Type | Description |
---|---|
Number | A timestamp after adding the specified number of minutes. |
applyCommand
Applies a command to the issue.
Parameters
Name | Type | Description |
---|---|---|
command | String | The command that is applied to the issue. |
runAs | User | Specifies the user by which the command is applied. If this parameter is not set, the command is applied on behalf of the current user. |
becomes
Checks whether a field is set to an expected value in the current transaction.
Parameters
Name | Type | Description |
---|---|---|
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`. |
canBeReadBy
Checks whether a user has permission to read the field.
Parameters
Name | Type | Description |
---|---|---|
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
Checks whether a user has permission to update the field.
Parameters
Name | Type | Description |
---|---|---|
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`. |
clearAttachments
Removes all of the attachments from the issue.
copy
Creates a copy of the issue.
Parameters
Name | Type | Description |
---|---|---|
project | Project | Project to create new issue in. Available since 2018.1.40575. |
Return Value
Type | Description |
---|---|
Issue | The copy of the original issue. |
hasTag
Checks whether the specified tag is attached to an issue.
Parameters
Name | Type | Description |
---|---|---|
tagName | String | The name of the tag to check for the issue. |
Return Value
Type | Description |
---|---|
Boolean | If the specified tag is attached to the issue, returns `true`. |
is
Checks whether a field is equal to an expected value.
Available since 2019.2.55603
Parameters
Name | Type | Description |
---|---|---|
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
Checks whether the value of a field is changed in the current transaction.
Parameters
Name | Type | Description |
---|---|---|
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`. |
isVisibleTo
Checks whether the issue is accessible by specified user.
Parameters
Name | Type | Description |
---|---|---|
user | User | The user to check. |
Return Value
Type | Description |
---|---|
Boolean | If the issue is accessible for the user, returns 'true'. |
oldValue
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
Name | Type | Description |
---|---|---|
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. |
pauseSLA
Pauses the timers for the current SLA applied to the issue.
Available since 2023.1
removeTag
Removes a tag with the specified name from an issue. If the specified tag is not attached to the issue, nothing happens. This method first searches through tags owned by the current user, then through all other visible tags. To remove a tag that is not visible to the current user, use the `applyCommand` method instead. Use "remove tag [tagName]" for the command parameter and specify the login for the owner of the tag in the `runAs` parameter.
Parameters
Name | Type | Description |
---|---|---|
name | String | The name of the tag to remove from the issue. |
Return Value
Type | Description |
---|---|
Tag | The tag that has been removed from the issue. |
Example
renderMarkup
Converts text in markdown to HTML. Use this method to send "pretty" notifications.
Parameters
Name | Type | Description |
---|---|---|
text | String | The string of text to convert to HTML. |
Return Value
Type | Description |
---|---|
String | Rendered markdown |
Example
required
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
Name | Type | Description |
---|---|---|
fieldName | string | The name of the field to check. |
message | string | The message that is displayed to the user that describes the field requirement. |
resumeSLA
Resumes the timers for the current SLA applied to the issue.
Available since 2023.1
was
Checks whether a field was equal to an expected value prior to the current transaction.
Available since 2019.2.55603
Parameters
Name | Type | Description |
---|---|---|
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`. |