Issue

Issue

Parameters

action

Creates a declaration of a rule that a user can apply to one or more issues with a command or menu option. The returned object is normally exported to the rule property. Otherwise, YouTrack does not treat it as a rule.

Parameters

Name	Type	Description
ruleProperties	Object	An object that defines the rule.

Properties of ruleProperties

Name	Type	Description
title	string	The human-readable name of the rule. Displayed in the administrative UI in YouTrack.
command	string	The custom command that triggers the action.
userInput	Object	An object that defines the information requested from the user who triggers the action rule. The userInput object has the following properties: type Type: string or Object The data type of the requested value. Supported types: 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 description Type: string The label for the control that collects additional information from the user.
guard	Issue~guardFunction	A function that is invoked to determine whether the action is applicable to an issue.
action	Issue~actionFunction	The function that is invoked when a user triggers this action.
requirements	Requirements	The fields and entities that must be available for the rule to run.

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

createDraft

Creates a new issue draft.

Available since 2025.1

Parameters

Name	Type	Description
project	Project	The project where the new issue draft belongs.
reporter	User	The reporter of the issue draft.

Return Value

Type	Description
Issue	The newly created issue draft.

createSharedDraft

Creates a new shared issue draft in the specified project. Unlike createDraft(), this method does not associate the draft with an individual reporter. Use the returned Issue object to populate the draft.

Available since 2025.1

Parameters

Name	Type	Description
project	Project	The project where the new issue draft belongs.

Return Value

Type	Description
Issue	The newly created issue draft.

findByExtensionProperties

Finds issues whose extension properties match the specified query.

Available since 2024.3.43260

Parameters

Name	Type	Description
extensionPropertiesQuery	Object	An object that maps extension property names to the values to match.

Return Value

Type	Description
Set .< Issue >	The issues whose extension properties match the query.

Example

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

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

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

onChange

Creates a declaration of a rule that runs when an issue changes. The returned object is normally exported to the rule property. Otherwise, YouTrack does not treat it as a rule.

Parameters

Name	Type	Description
ruleProperties	Object	An object that defines the rule.

Properties of ruleProperties

Name	Type	Description
title	string	The human-readable name of the rule. Displayed in the administrative UI in YouTrack.
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.
action	Issue~actionFunction	The function that is invoked on an issue change.
requirements	Requirements	The fields and entities that must be available for the rule to run.
runOn	Object	Determines which issue events trigger the on-change rule. When not specified, the rule is triggered on an issue change. The runOn object has the following properties: change Type: boolean When true, the rule is triggered on an issue change. removal Type: 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

Creates a declaration of a rule that runs on a schedule. The returned object is normally exported to the rule property. Otherwise, YouTrack does not treat it as a rule.

Parameters

Name	Type	Description
ruleProperties	Object	An object that defines the rule.

Properties of ruleProperties

Name	Type	Description
title	string	The human-readable name of the rule. Displayed in the administrative UI in YouTrack.
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.
cron	string	A cron expression that specifies the interval for applying the rule.
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.
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.
action	Issue~actionFunction	The function that is invoked on schedule for each issue that matches the search.
requirements	Requirements	The fields and entities that must be available for the rule to run.

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 IDs of major issues every 5 seconds', search: '#Major', cron: '0/5 * * * * ?', action: function(ctx) { console.log(ctx.issue.id); } });

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	An object that defines the SLA policy.

Properties of ruleProperties

Name	Type	Description
title	string	The human-readable name of the SLA policy. Displayed in the administrative UI in YouTrack.
guard	Issue~slaGuardFunction	A function that is invoked to determine whether the policy is applicable to the ticket.
onEnter	Issue~slaEnterFunction	A function that is invoked when the SLA policy starts applying to the ticket.
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.
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.
requirements	Requirements	The fields and entities that must be available for the rule to run. 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

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

Creates a declaration of a state-machine rule. The state machine restricts transitions between values in a custom field. It can run actions when the field is set to a value, changes from a value, or moves between two specific values. The returned object is normally exported to the rule property. Otherwise, YouTrack does not treat it as a rule.

Parameters

Name	Type	Description
ruleProperties	Object	An object that defines the rule.

Properties of ruleProperties

Name	Type	Description
title	string	The human-readable name of the rule. Displayed in the administrative UI in YouTrack.
fieldName	string	The name of a field that is managed by the state-machine rule. Declare either fieldName or stateFieldName, not both.
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.
states	Object	A list of values for a custom field and the possible transitions between them. Declare either states or defaultStateMachine, not both.
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.
typeFieldName	string	The name of a field that defines which state-machine applies to the managed field.
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 defined by ruleProperties.typeFieldName. Object values have the same structure shown for states in the example. This parameter is mandatory when ruleProperties.typeFieldName is specified.
requirements	Requirements	The fields and entities that must be available for the rule to run.

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

Attaches a file to the issue. In the current transaction, this method makes issue.attachments.isChanged return true.

Available since 2019.2.53994

Parameters

Name	Type	Description
content	InputStream, String, JsonForIssueAddAttachment	The file content in binary form or as a base64 data URI. Base64 content must use the data:[MIME type];base64,[content] syntax. Alternatively, pass an object described by JsonForIssueAddAttachment.
name	String	The name of the file.
charset	String	The character encoding of the file. This parameter is used only for 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. In the current transaction, this method makes issue.comments.isChanged return true.

Parameters

Name	Type	Description
text	String, JsonForIssueAddComment	The comment text, or an object described 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.

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.

addWorkItem

Adds a work item to the issue.

Parameters

Name	Type	Description
description	String, JsonForIssueAddWorkItem	The work item description, or an object described 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, the extra minutes are 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. The optional runAs user supplies the permissions used to execute the command. It does not impersonate that user for issue history: the update is still attributed to the user under whose account the workflow is running.

Parameters

Name	Type	Description
command	String	The command that is applied to the issue.
runAs	User	Specifies the user whose permissions are used to apply the command. If this parameter is not set, the permissions of the current user are used. This parameter does not change the user recorded in issue history.

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	The Project where the new issue is created. 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.
ignoreVisibilitySettings	Boolean	When true, checks all matching tags without regard to their visibility settings. When false (default), checks only matching tags that are visible to the current user.

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 specified user can access the issue.

Parameters

Name	Type	Description
user	User	The user to check.

Return Value

Type	Description
Boolean	If the specified user can access the issue, 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 current 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, returns the previous value of the field. Otherwise, returns 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 the issue. If the tag is not attached, nothing happens. The method searches tags owned by the current user first, followed by all other visible tags.

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.

renderMarkup

Converts Markdown text to HTML for use in formatted notifications.

Parameters

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

Return Value

Type	Description
String	The rendered HTML.

Example

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

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

setDefaultFieldValues

Sets the default custom field values for the issue. Applies only for empty fields.

Available since 2025.3

tag

Applies the tag to the issue.

Available since 2025.3

Parameters

Name	Type	Description
tag	Tag	The tag object.

untag

Removes the tag from the issue.

Available since 2025.3

Parameters

Name	Type	Description
tag	Tag	The tag object.

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.