Issue

Last modified: 11 March 2025

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

Issue(reporter, project, summary)

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

static action(ruleProperties, ruleProperties.title, ruleProperties.command, ruleProperties.userInput, ruleProperties.userInput.type, ruleProperties.userInput.description, ruleProperties.guard, ruleProperties.action, ruleProperties.requirements)

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.

Type	Description
Object	The object representation of the rule.

var entities = require('@jetbrains/youtrack-scripting-api/entities');
exports.rule = entities.Issue.action({
  title: 'Log comments',
  command: 'log',
  guard: function(ctx) {
    return ctx.issue.isReported;
  },
  action: function(ctx) {
    ctx.issue.comments.forEach(function(comment) {
      console.log(comment.text);
    });
  }
});

findByExtensionProperties

static findByExtensionProperties(extensionPropertiesQuery)

Name	Type	Description
extensionPropertiesQuery	Object	The extension properties query.

Type	Description
Set.<Issue>	The set of Issue entities found by the extension properties query.

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

findById

static findById(id)

Name	Type	Description
id	String	The issue ID.

Type	Description
Issue	The issue that is assigned the specified ID.

var myIssue = entities.Issue.findById("NP-15971");

onChange

static onChange(ruleProperties, ruleProperties.title, ruleProperties.guard, ruleProperties.action, ruleProperties.requirements, ruleProperties.runOn, ruleProperties.runOn.change, ruleProperties.runOn.removal)

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.

Type	Description
Object	The object representation of the rule.

var entities = require('@jetbrains/youtrack-scripting-api/entities');
exports.rule = entities.Issue.onChange({
  title: 'On issue change, log its ID',
  action: function(ctx) {
    console.log(ctx.issue.id);
  }
});

onSchedule

static onSchedule(ruleProperties, ruleProperties.title, ruleProperties.search, ruleProperties.cron, ruleProperties.muteUpdateNotifications, ruleProperties.modifyUpdatedProperties, ruleProperties.action, ruleProperties.requirements)

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.

Type	Description
Object	The object representation of the rule.

var entities = require('@jetbrains/youtrack-scripting-api/entities');
exports.rule = entities.Issue.onSchedule({
  title: 'Log IDs of major issues every 5 seconds',
  search: '#Major',
  cron: '0/5 * * * * ?',
  action: function(ctx) {
    console.log(ctx.issue.id);
  }
});

sla

static sla(ruleProperties, ruleProperties.title, ruleProperties.guard, ruleProperties.onEnter, ruleProperties.action, ruleProperties.onBreach, ruleProperties.requirements)

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.

Type	Description
Object	The object representation of the SLA policy.

const entities = require('@jetbrains/youtrack-scripting-api/entities');
exports.rule = entities.Issue.sla({
  title: "Support",
  guard: (ctx) => {
    return false;
  },
  onEnter: (ctx) => {
    console.log('onEnter', ctx.issue.id);
  },
  action: (ctx) => {
    console.log('action', ctx.issue.id);
  },
  onBreach: (ctx) => {
    console.log('onBreach', ctx.issue.id, ctx.breachedField);
  },

  requirements: {
    firstReplyField: {
      type: entities.Field.dateTimeType,
      name: 'First Reply'
    },
    state: {
      type: entities.State.fieldType,
      name: 'State'
    }
  }
});

stateMachine

static stateMachine(ruleProperties, ruleProperties.title, ruleProperties.fieldName, ruleProperties.stateFieldName, ruleProperties.states, ruleProperties.defaultMachine, ruleProperties.typeFieldName, ruleProperties.alternativeMachines, ruleProperties.requirements)

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.

Type	Description
Object	The object representation of the rule.

var entities = require('@jetbrains/youtrack-scripting-api/entities');
exports.rule = entities.Issue.stateMachine({
  title: 'Status state machine',
  fieldName: 'Status',
  states: {
    Open: {
      initial: true,
      transitions: {
        start: {
          targetState: 'In progress'
        }
      }
    },
    'In progress': {
      onEnter: function(ctx) {
        ctx.issue.fields.Assignee = ctx.currentUser;
      },
      transitions: {
        fix: {
          targetState: 'Fixed'
        },
        reopen: {
          targetState: 'Open'
        }
      }
    },
    Fixed: {
      transitions: {
      }
    }
  },
  requirements: {
    Assignee: {
      type: entities.User.fieldType
    }
  }
});

addAttachment

addAttachment(content, name, charset, mimeType)

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.

Type	Description
IssueAttachment	The attachment that is added to the issue.

addComment

addComment(text, author)

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.

Type	Description
IssueComment	A newly created comment.

addTag

addTag(name)

Name	Type	Description
name	String	The name of the tag to add to the issue.

Type	Description
Tag	The tag that has been added to the issue.

issue.addTag('doit');

addWorkItem

addWorkItem(description, date, author, duration, type)

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.

Type	Description
IssueWorkItem	The new work item.

afterMinutes

afterMinutes(initialTime, minutes, calendar, considerPauses)

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.

Type	Description
Number	A timestamp after adding the specified number of minutes.

applyCommand

applyCommand(command, runAs)

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

becomes(fieldName, expected)

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

canBeReadBy

canBeReadBy(fieldName, user)

Name	Type	Description
fieldName	string	The name of the field.
user	User	The user for whom the permission to read the field is checked.

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

canBeWrittenBy

canBeWrittenBy(fieldName, user)

Name	Type	Description
fieldName	string	The name of the field.
user	User	The user for whom the permission to update the field is checked.

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

copy

copy(project)

Name	Type	Description
project	Project	Project to create new issue in. Available since 2018.1.40575.

Type	Description
Issue	The copy of the original issue.

hasTag

hasTag(tagName)

Name	Type	Description
tagName	String	The name of the tag to check for the issue.

Type	Description
Boolean	If the specified tag is attached to the issue, returns `true`.

is

is(fieldName, expected)

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

isChanged

isChanged(fieldName)

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

isVisibleTo

isVisibleTo(user)

Name	Type	Description
user	User	The user to check.

Type	Description
Boolean	If the issue is accessible for the user, returns 'true'.

oldValue

oldValue(fieldName)

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

removeTag

removeTag(name)

Name	Type	Description
name	String	The name of the tag to remove from the issue.

Type	Description
Tag	The tag that has been removed from the issue.

issue.removeTag('waiting for reply');

renderMarkup

renderMarkup(text)

Name	Type	Description
text	String	The string of text to convert to HTML.

Type	Description
String	Rendered markdown

issue.Assignee.notify('Comment added:', issue.renderMarkup(comment.text));

required

required(fieldName, message)

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.

was

was(fieldName, expected)

Issue﻿

Properties﻿

Constructors﻿

Issue﻿

Methods﻿

action﻿

findByExtensionProperties﻿

findById﻿

onChange﻿

onSchedule﻿

sla﻿

stateMachine﻿

addAttachment﻿

addComment﻿

addTag﻿

addWorkItem﻿

afterMinutes﻿

applyCommand﻿

becomes﻿

canBeReadBy﻿

canBeWrittenBy﻿

clearAttachments﻿

copy﻿

hasTag﻿

is﻿

isChanged﻿

isVisibleTo﻿

oldValue﻿

pauseSLA﻿

removeTag﻿

renderMarkup﻿

required﻿

resumeSLA﻿

was﻿

Issue

Properties

Constructors

Issue

Methods

action

findByExtensionProperties

findById

onChange

onSchedule

sla

stateMachine

addAttachment

addComment

addTag

addWorkItem

afterMinutes

applyCommand

becomes

canBeReadBy

canBeWrittenBy

clearAttachments

copy

hasTag

is

isChanged

isVisibleTo

oldValue

pauseSLA

removeTag

renderMarkup

required

resumeSLA

was