YouTrack InCloud 2017.2 Help

Issue

Extends: BaseEntity

Represents YouTrack issue.

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.

 

Properties

NameTypeDescriptionRead-only
attachments Set.<IssueAttachment> The list of attachments for the issue. /help/img/youtrack/2017.2/checkbox-marked.png
becomesReported Boolean `true` in case the issue becomes reported in the current transaction.

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.2/checkbox-marked.png
becomesResolved Boolean `true` in case the issue is assigned a state that is considered resolved in the current transaction. /help/img/youtrack/2017.2/checkbox-marked.png
becomesUnresolved Boolean `true` in case the issue is assigned a state that is considered unresolved in the current transaction. /help/img/youtrack/2017.2/checkbox-marked.png
comments Set.<IssueComment> A list of comments for the issue. /help/img/youtrack/2017.2/checkbox-marked.png
created Number The date when the issue was created. /help/img/youtrack/2017.2/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 instance, if `issueA` duplicates `issueB` and `issueB` duplicates`issueC`, then `issueA.getDuplicateRoot()` would return `issueC`. /help/img/youtrack/2017.2/checkbox-marked.png
editedComments Set.<IssueComment> The comments that are edited in the current transaction.Comments that are added and removed are not considered as edited.These values are represented by the `issue.comments.added` and`issue.comments.removed` properties. /help/img/youtrack/2017.2/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" andaccessed directly.

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

id String Issue ID.

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

/help/img/youtrack/2017.2/checkbox-marked.png
isReported Boolean `true` in case the issue is already reported or becomes reported in current transaction (stages 3 and 4). To apply changes to an issue draft (stage 2), 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.2/checkbox-marked.png
isResolved Boolean `true` if the issue is assigned a state that is considered resolved. /help/img/youtrack/2017.2/checkbox-marked.png
isStarred Boolean Whether any user has added the star tag to the issue. /help/img/youtrack/2017.2/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.2/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 <b>All Users</b> group.
permittedGroups Set.<UserGroup> User groups for which the issue is visible.
permittedUsers Set.<User> Users for whom the issue is visible.
project Project The project to which the issue is assigned.
reporter User The user who reported the issue.

issue.fields.Assignee = issue.reporter;

/help/img/youtrack/2017.2/checkbox-marked.png
resolved Number Issue resolution time. /help/img/youtrack/2017.2/checkbox-marked.png
sprints Set.<Sprint> All sprints this issue belongs 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.2/checkbox-marked.png
updatedBy User The user who last updated the issue. /help/img/youtrack/2017.2/checkbox-marked.png
url String The issue URL.

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

/help/img/youtrack/2017.2/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.2/checkbox-marked.png
workItems Set.<IssueWorkItem> Work items of the issue. /help/img/youtrack/2017.2/checkbox-marked.png

Methods

 

action

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

Creates a declaration of an action that a user can apply to one issue or multiple issues using YouTrack commandwindow or toolbar action.Result of this call are normally exported under 'rule' property, otherwise it is not treated as a 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); }); } });

Parameters:

NameTypeDescription
ruleProperties Object JSON describing rule properties.
ruleProperties.title string human readable name of the rule. Will be displayed in YouTrack UI.
ruleProperties.command string custom command which will trigger this action.
ruleProperties.guard Issue~guardFunction function that is invoked to check if the action is applicable to an issue.
ruleProperties.action Issue~actionFunction function that is invoked when a user triggers this action.
ruleProperties.requirements Requirements that environment need to meet for this script to work.

Returns:

TypeDescription
Object Rule representation.

 

findById

static findById(id)

Finds an issue by it's visible id.

Parameters:

NameTypeDescription
id String Issue id.

Returns:

TypeDescription
Issue The issue.

 

onChange

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

Creates a declaration of a rule that will be triggered when an issue is changed.Result of this call are normally exported under 'rule' property, otherwise it is not treated as a 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); } });

Parameters:

NameTypeDescription
ruleProperties Object JSON describing rule properties.
ruleProperties.title string human readable name of the rule. Will be displayed in YouTrack UI.
ruleProperties.action Issue~actionFunction function that is invoked on issue change.
ruleProperties.requirements Requirements that environment need to meet for this script to work.

Returns:

TypeDescription
Object Rule representation.

 

onSchedule

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

Creates a declaration of a rule that will be triggered on schedule.Result of this call are normally exported under 'rule' property, otherwise it is not treated as a rule.

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

Parameters:

NameTypeDescription
ruleProperties Object JSON describing rule properties.
ruleProperties.title string human readable name of the rule. Will be displayed in YouTrack UI.
ruleProperties.search string, function YouTrack search string or a function with no parameters that returns such string.The action will be execute for issues that match the search and belong to the project this rule is attached to.
ruleProperties.cron string cron expression that specifieds the triggering interval.
ruleProperties.action Issue~actionFunction function that is invoked on schedule for each issue that matches the search.
ruleProperties.requirements Requirements that environment need to meet for this script to work.

Returns:

TypeDescription
Object Rule representation.

 

stateMachine

static stateMachine(ruleProperties, ruleProperties.title, ruleProperties.states, ruleProperties.requirements)

Creates declaration of a state machine. The state machine imposes restrictions on how an issue is transited fromone state to another. You can execute certain actions when the issue enters a state, exits it, or transits betweentwo distinct states.Result of this call are normally exported under 'rule' property, otherwise it is not treated as a 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 } } });

Parameters:

NameTypeDescription
ruleProperties Object JSON describing rule properties.
ruleProperties.title string human readable name of the rule. Will be displayed in YouTrack UI.
ruleProperties.states Array.<Object> list of field values and transitions between them.
ruleProperties.requirements Requirements that environment need to meet for this script to work.

Returns:

TypeDescription
Object Rule representation.

 

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.

Returns:

TypeDescription
IssueComment A newly created comment.

 

addTag

addTag(name)

Add a tag with the specified name to an issue. YouTrack adds the first matching tagthat 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 <em>star</em> 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 " for the command parameter and specify the owner of the tag in the runAs parameter.

addTag('doit');

Parameters:

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

Returns:

TypeDescription
IssueTag Entity of type IssueTag representing a tag that has been added to the issue.

 

addWorkItem

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

Adds a work item to the issue.

Parameters:

NameTypeDescription
description String, JsonForIssueAddWorkItem either work item text. Alternatively, pass a JSON specified by JsonForIssueAddWorkItem
date Number work date.
author User work author.
duration Number work duration in minutes.
type WorkItemType work type.

Returns:

TypeDescription
IssueWorkItem a newly created 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 that a value a field receives in the current transaction is equal to an expected one.

Parameters:

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

Returns:

TypeDescription
boolean `true` in case the expectation is met.

 

canBeReadBy

canBeReadBy(fieldName, user)

Checks if a field can be read by a user.

Parameters:

NameTypeDescription
fieldName string name of the field.
user User to check access for.

Returns:

TypeDescription
boolean `true` in case the field can be read by the user.

 

canBeWrittenBy

canBeWrittenBy(fieldName, user)

Checks if a field can be written by a user.

Parameters:

NameTypeDescription
fieldName string name of the field.
user User to check access for.

Returns:

TypeDescription
boolean `true` in case the field can be written by the user.

 

clearAttachments

clearAttachments()

Removes all of the attachments from the issue.

 

copy

copy()

Creates a copy of the issue.

Returns:

TypeDescription
Issue Copy of this issue.

 

createCopy

createCopy()

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

Returns:

TypeDescription
Issue copy of this 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.

Returns:

TypeDescription
Boolean `true` in case the tag is attached.

 

isChanged

isChanged(fieldName)

Checks if a field is changed in the current transaction.

Parameters:

NameTypeDescription
fieldName string name of the field (e.g. 'summary') to check.

Returns:

TypeDescription
boolean `true` in case the field is changed in the current transaction.

 

oldValue

oldValue(fieldName)

Returns the previous value of a single-valued field before an update was applied. In case the field is not changedin the transaction, this value is equal to the current value of the field.

Parameters:

NameTypeDescription
fieldName string name of the field (e.g. 'updated') to get previous value of.

Returns:

TypeDescription
Object previous value of the field.

 

removeTag

removeTag(name)

Remove 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 current user, then through all other tags visible.To remove a tag that is not visible to a current user, use the applyCommand method instead. Use "remove tag "for the command parameter and specify the login for the owner of the tag in the runAs parameter.

removeTag('waiting for reply');

Parameters:

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

Returns:

TypeDescription
IssueTag Entity of type IssueTag representing a tag has been removed from the issue.

 

required

required(fieldName, message)

Checks if a the entity has a field denoted by field name set, shows error message otherwise.

Parameters:

NameTypeDescription
fieldName string name of the field to check.
message string message to show in case the field is not set.

 

wikify

wikify(text)

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

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

Parameters:

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

Returns:

TypeDescription
String Wikified string

 

Last modified: 9 August 2017