YouTrack Standalone 2020.3 Help

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`.

Available since 2017.4.37915

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`.

boards

Set.<Sprint>

Read-only.  The collection of boards that this issue has been added to.

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.

duplicateCluster

Number

Read-only.  TODO documentation missing

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

externalId

String

Read-only.  The visible ID of an issue or similar object in an originating third-party system.

Available since 2018.2.42312

externalUrl

String

Read-only.  The URL for an issue or similar object in an originating third-party system.

Available since 2018.2.42312

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`.

isUsingMarkdown

Boolean

When `true`, the issue description is parsed as Markdown. When `false`, the issue description is parsed as YouTrack Wiki. Changing this value does not transform the markup from one syntax to another.

Available since 2017.4.38870

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.

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.

sprints

Set.<Sprint>

Read-only.  The collection of sprints that this issue has been added to.

summary

String

The text that is entered as the issue summary.

tags

Set.<IssueTag>

The list of tags that are attached to an issue.

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)

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

static action(ruleProperties, ruleProperties.title, ruleProperties.command, ruleProperties.guard, ruleProperties.action, ruleProperties.requirements)

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.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

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); }); } });

 

findById

static findById(id)

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.

 

onChange

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

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.action

Issue~actionFunction

The function that is invoked on 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 issue change.

ruleProperties.runOn.change

boolean

When `true`, the rule is triggered on 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

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.action, ruleProperties.requirements)

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.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

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

 

stateMachine

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

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

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)

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, JsonForIssueAddAttachment

The content of the file in binary 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

addComment(text, author)

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

addTag(name)

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

IssueTag

The tag that has been added to the issue.

Example

issue.addTag('doit');

 

addWorkItem

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

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.

 

applyCommand

applyCommand(command, runAs)

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

becomes(fieldName, expected)

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

canBeReadBy(fieldName, user)

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

canBeWrittenBy(fieldName, user)

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

clearAttachments()

Removes all of the attachments from the issue.

 

copy

copy(project)

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

hasTag(tagName)

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

is(fieldName, expected)

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

isChanged(fieldName)

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

isVisibleTo(user)

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

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

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.

 

removeTag

removeTag(name)

Removes a tag with the specified name from an issue. If the specified tag is not attached to the issue, an exception is thrown. 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

IssueTag

The tag that has been removed from the issue.

Example

issue.removeTag('waiting for reply');

 

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

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)

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`.

 

wikify

wikify(text, usingMarkdown)

Converts text with Markdown or YouTrack Wiki markup to HTML. Use this method to send "pretty" notifications.

Parameters

Name

Type

Description

text

String

The string of text to convert to HTML.

usingMarkdown

Boolean

If `true`, the markup is parsed as Markdown. If `false`, the markup is parsed as YouTrack Wiki. If omitted, issue.isUsingMarkdown is used implicitly. Available since 2018.1.40100.

Return Value

Type

Description

String

The wikified string.

Example

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

 

Last modified: 28 October 2020