YouTrack Standalone 2017.3 Help

Issue

Represents an issue in YouTrack.

Extends BaseEntity.

Properties

NameTypeDescriptionRead-only
attachments Set.<IssueAttachment> The set of attachments that are attached to the issue. /help/img/youtrack/2017.3/checkbox-marked.png
becomesReported Boolean 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 }

/help/img/youtrack/2017.3/checkbox-marked.png
becomesResolved Boolean If the issue is assigned a state that is considered resolved in the current transaction, this property is `true`. /help/img/youtrack/2017.3/checkbox-marked.png
becomesUnresolved Boolean If the issue is assigned a state that is considered unresolved in the current transaction. this property is `true`. /help/img/youtrack/2017.3/checkbox-marked.png
comments Set.<IssueComment> A list of comments for the issue. /help/img/youtrack/2017.3/checkbox-marked.png
created Number The date when the issue was created. /help/img/youtrack/2017.3/checkbox-marked.png
description String The text that is entered as the issue description.
duplicateRoot Issue 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`. /help/img/youtrack/2017.3/checkbox-marked.png
editedComments Set.<IssueComment> 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. /help/img/youtrack/2017.3/checkbox-marked.png
fields Fields All issue custom fields. Note that custom fields are the fields like `Assignee`, `State`, `Priority`, etc. (those values which are defined at `Custom fields` administration UI). The values like `reporter`, `project`, etc., are called just "fields" and accessed directly.

if (issue.fields.becomes(ctx.Priority, ctx.Priority.Critical) { issue.fields.Assignee = issue.project.leader; }

id String The issue ID.

user.notify('Issue is overdue', 'Please, look at the issue: ' + issue.id);

/help/img/youtrack/2017.3/checkbox-marked.png
isReported Boolean 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!'); } });

/help/img/youtrack/2017.3/checkbox-marked.png
isResolved Boolean If the issue is currently assigned a state that is considered resolved, this property is `true`. /help/img/youtrack/2017.3/checkbox-marked.png
isStarred Boolean If any user has added the star tag to watch the issue, this property is `true`. /help/img/youtrack/2017.3/checkbox-marked.png
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 The issue number in the project. /help/img/youtrack/2017.3/checkbox-marked.png
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.
reporter User The user who reported (created) the issue.

issue.fields.Assignee = issue.reporter;

/help/img/youtrack/2017.3/checkbox-marked.png
resolved Number The date and time when the issue was assigned a state that is considered to be resolved. /help/img/youtrack/2017.3/checkbox-marked.png
sprints Set.<Sprint> 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 The date when the issue was last updated. /help/img/youtrack/2017.3/checkbox-marked.png
updatedBy User The user who last updated the issue. /help/img/youtrack/2017.3/checkbox-marked.png
url String The absolute URL that points to the issue.

user.notify('Issue is overdue', 'Please, look at the issue: ' + issue.url);

/help/img/youtrack/2017.3/checkbox-marked.png
votes Number The number of votes for an issue. For vote-related methods, see User.canVoteIssue, User.voteIssue, User.canUnvoteIssue, and User.unvoteIssue. /help/img/youtrack/2017.3/checkbox-marked.png
workItems Set.<IssueWorkItem> The set of work items that have been added to the issue. /help/img/youtrack/2017.3/checkbox-marked.png

Constructors


Issue

Issue(reporter, project, summary)

Parameters

NameTypeDescription
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

NameTypeDescription
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

TypeDescription
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

NameTypeDescription
id String The issue ID.

Return Value

TypeDescription
Issue The issue that is assigned the specified ID.

 

onChange

static onChange(ruleProperties, ruleProperties.title, ruleProperties.action, ruleProperties.requirements)

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

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

Return Value

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

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

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

Creates 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

NameTypeDescription
ruleProperties Object A JSON object that defines the properties for the rule.
ruleProperties.title string A human-readable name of the rule. Displayed in the administrative UI in YouTrack.
ruleProperties.states Array.<Object> A list of values for a custom field and the possible transitions between them.
ruleProperties.requirements Requirements The set of entities that must be present for the script to work as expected.

Return Value

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

 

addComment

addComment(text, author)

Adds a comment to the issue. Makes `issue.comments.isChanged` return `true` for the current transaction.

Parameters

NameTypeDescription
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

TypeDescription
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

NameTypeDescription
name String The name of the tag to add to the issue.

Return Value

TypeDescription
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

NameTypeDescription
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

TypeDescription
IssueWorkItem The new work item.

 

applyCommand

applyCommand(command, runAs)

Applies a command to the issue.

Parameters

NameTypeDescription
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

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

Return Value

TypeDescription
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

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

Return Value

TypeDescription
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

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

Return Value

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

 

clearAttachments

clearAttachments()

Removes all of the attachments from the issue.

 

copy

copy()

Creates a copy of the issue.

Return Value

TypeDescription
Issue The copy of the original issue.

 

createCopy

createCopy()

Creates a copy of the issue. No workflows will be triggered for the newly created issue.

Return Value

TypeDescription
Issue The copy of the original issue.

 

hasTag

hasTag(name)

Checks whether the specified tag is attached to an issue.

Parameters

NameTypeDescription
name String The name of the tag to check for the issue.

Return Value

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

 

isChanged

isChanged(fieldName)

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

Parameters

NameTypeDescription
fieldName string The name of the field to check.

Return Value

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

 

isVisibleTo

isVisibleTo(user)

Checks whether the issues is accessible by specified user.

Parameters

NameTypeDescription
user User The user to check

Return Value

TypeDescription
Boolean If the issue is accessbie 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, this value is equal to the current value of the field.

Parameters

NameTypeDescription
fieldName string The name of the field.

Return Value

TypeDescription
Object previous If the field is changed in the current transaction, the previous value of the field. Otherwise, the current value of the field.

 

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

NameTypeDescription
name String The name of the tag to remove from the issue.

Return Value

TypeDescription
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

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

 

wikify

wikify(text)

Converts text with wiki markup to HTML. Use this method to send "pretty" notifications.

Parameters

NameTypeDescription
text String The string of text to convert to HTML.

Return Value

TypeDescription
String The wikified string

Example

issue.Assignee.notify('Issue is commented', issue.wikify(comment.text));

 

Last modified: 4 October 2017