Developer Portal for YouTrack and Hub Help

entities

Contains definitions for the entities in YouTrack that are accessible to workflows.

Types

This module supports the following object types:

Type

Description

AbstractVcsItem

Represents VCS-related items such as commits and pull requests.

Agile

Represents an agile board and the set of sprints that belong to the board.

Article

Represents an article in YouTrack.

ArticleAttachment

Represents a file that is attached to an article.

ArticleComment

Represents a comment that is added to an article.

Attributes

Represents the collection of custom attributes that have been added to user profiles. To retrieve a value that is stored in the profile for a referenced user, use the attribute value as the key. The entire object is read-only.

BaseArticle

The base class for article.

BaseArticleAttachment

The base class for article comment.

BaseArticleComment

The base class for article comment.

BaseComment

The base class for issue comment.

BaseEntity

The common ancestor for all entity types.

BaseWorkItem

The base class for issue work items.

Build

Represents a value that is stored in a custom field that stores a build type.

BundleProjectCustomField

Represents a custom field in a project that stores a predefined set of values.

Calendar

Represents a group of business hours settings in a helpdesk project. In the Workflow API, such a group is called a Calendar.

Calendar24x7

Represents a group of 24x7 business hours settings in a helpdesk project. In the Workflow API, such a group is called a Calendar24x7.

ChangesProcessor

An entity that retrieves VCS changes and creates their representation in YouTrack.

EnumField

Represents a value in a custom field that stores a predefined set of values.

Field

Represents a value that is stored in a custom field. The custom fields themselves are represented by the Fields class.

Fields

Represents the custom fields that are used in an issue. The actual set of custom fields that are used for each issue is configured on a per-project basis. The properties shown here correspond with the default custom fields in YouTrack. Additional custom fields that have been attached to a project are also available.

Gantt

Represents a Gantt chart.

GroupProjectCustomField

Represents a custom field in a project that stores a UserGroup type.

Issue

Represents an issue in YouTrack.

IssueAttachment

Represents a file that is attached to an issue.

IssueComment

Represents a comment that is added to an issue.

IssueLinkPrototype

Represents an issue link type.

IssueTag

Deprecated. Use Tag instead.

IssueWorkItem

Represents a work item that has been added to an issue.

Iterator

An object that enables traversal through the elements in a collection.

JsonForArticleAddComment
JsonForArticleConstructor
JsonForIssueAddAttachment
JsonForIssueAddComment
JsonForIssueAddWorkItem
JsonForIssueCommentAddAttachment
JsonForIssueConstructor
JsonForUserNotify
OwnedField

Represents a value in a custom field that has a user associated with it, a so-called owner.

PeriodProjectCustomField

Represents a custom field in a project that stores a value as a period type. We use org.joda.time.Period as a base class for period values. While you can read the class documentation at http://joda-time.sourceforge.net/apidocs/org/joda/time/Period.html, please note that we support only class members which use the Period class and primitive types like String and int.

PersistentFile

Represents the common ancestor for all persistent files that are available in YouTrack.

Project

Represents a YouTrack project.

ProjectCustomField

Represents a custom field that is available in a project.

ProjectVersion

Represents a value in a custom field that stores a version type.

PullRequest

Represents a pull or merge request that is attached to an issue.

PullRequestState

Represents a pull request state.

Requirement

A single element in a set of Requirements

Requirements

The `Requirements` object serves two purposes. First, it functions as a safety net. It specifies the set of entities that must exist for a rule to work as expected. Whenever one or more rule requirements are not met, corresponding errors are shown in the workflow administration UI. The rule is not executed until all of the problems are fixed. Second, it functions as a reference. Each entity in the requirements is plugged into the `context` object, so you can reference entities from inside your context-dependent functions (like an `action` function). There are two types of requirements: project-wide and system-wide. Project-wide requirements contain a list of custom fields that must be attached to each project that uses the rule as well as the required values from the sets of values for each custom field. System-wide requirements contain a list of other entities that must be available in YouTrack. This includes users, groups, projects, issues, tags, saved searches, and issue link types.

SavedQuery

Represents a saved search.

Set

The `Set` object stores unique values of any type, whether primitive values or object references. The Set is used as storage for all multi-value objects in this API: custom fields that store multiple values, issue links, issues in a project, and so on. You can access single values in the collection directly (see first(), last(), get(index)), use an iterator (see entries(), values()), or traverse with forEach(visitor) and find(predicate) methods. The workflow API is based on ECMAScript 5.1. This Set implementation mimics the functionality supported by the ES 6 Set interface.

SimpleCalendar

Represents a work days calendar in YouTrack.

SimpleProjectCustomField

Base class for custom fields that store simple values like strings and numbers.

Sprint

Represents a sprint that is associated with an agile board. Each sprint can include issues from one or more projects.

State

Represents a value in a custom field that stores a state type.

Tag

Represents a tag.

TextProjectCustomField

Represents a custom field that stores a string of characters as text. When displayed in an issue, the text is shown as formatted in Markdown.

User

Represents a user account in YouTrack.

UserGroup

Represents a group of users.

UserProjectCustomField

Represents a custom field in a project that stores values as a user type.

VcsChange

Represents a commit that is attached to an issue.

VcsServer

Represents a VCS server.

WatchFolder

Represents a common ancestor of classes that represent tags and saved searches.

WorkItemAttributeValue

Value of a work item attribute.

WorkItemType

Represents a work type that can be assigned to a work item.

XdSlaPausedInterval

Represents an SLA paused interval with start and stop times

Functions

actionFunction

actionFunction(ctx, ctx.issue, ctx.currentUser, ctx.isSilentOperation)

This function is called by different events depending on the rule type: when a change is applied to an issue (on-change rules), when a command is executed (action rules), or according to a predefined schedule (scheduled rules). This function is called separately for each related issue.

Parameters

Name

Type

Description

ctx

Object

The execution context. Along with the parameters listed below, the context also contains objects that you describe in the Requirements.

ctx.issue

Issue

The current issue.

ctx.currentUser

User

The user who executes the rule.

ctx.isSilentOperation

Boolean

When `true`, the rule is triggered in reaction to a command that is applied without notification. When `false`, the rule is triggered in reaction to a command that is applied normally. Available since 2017.4.38771.

Example

action: function(ctx) { console.log('Action for issue ' + ctx.issue.id); }

 

guardFunction

guardFunction(ctx, ctx.issue, ctx.currentUser)

This function is called to determine whether an action function can be applied to an issue. Guard functions are used in on-change rules, action rules, and in transitions between values of a state-machine rule. On-schedule rules also support guard functions, but this rule type includes a `search` property that has a similar purpose.

Parameters

Name

Type

Description

ctx

Object

The execution context. Along with the parameters listed below, the context also contains objects that you describe as Requirements.

ctx.issue

Issue

The current issue.

ctx.currentUser

User

The user who executes the rule.

Example

guard: function(ctx) { return ctx.issue.State.isResolved; }

 

slaActionFunction

slaActionFunction(ctx, ctx.issue, ctx.currentUser)

This function is called when the SLA policy needs to update a ticket. For example, it can pause the timers according to the SLA pausing settings, or it can resume the timers when there is a new comment from the customer. Only SLA policy scripts use this function.

Parameters

Name

Type

Description

ctx

Object

The execution context. Along with the parameters listed below, the context also contains objects that you describe as Requirements.

ctx.issue

Issue

The current ticket.

ctx.currentUser

User

The user who makes updates after which the SLA policy will update the ticket.

Example

action: (ctx) => { console.log('action', ctx.issue.id); }

 

slaBreachFunction

slaBreachFunction(ctx, ctx.breachedField, ctx.issue, ctx.currentUser)

This function is called when one of the SLA goals is breached. Only SLA policy scripts use this function.

Parameters

Name

Type

Description

ctx

Object

The execution context. Along with the parameters listed below, the context also contains objects that you describe as Requirements.

ctx.breachedField

Object

The timer custom field where the time goal has been breached for this ticket.

ctx.issue

Issue

The current ticket.

ctx.currentUser

User

The special workflow user that is considered to be the actor for triggering this function. This is a system user account that is granted a full set of permissions.

Example

onBreach: (ctx) => { console.log('onBreach', ctx.issue.id, ctx.breachedField); }

 

slaEnterFunction

slaEnterFunction(ctx, ctx.issue, ctx.currentUser)

This function is called when the SLA policy starts applying to the ticket. For example, it initialises the timers according to the SLA settings. Only SLA policy scripts use this function.

Parameters

Name

Type

Description

ctx

Object

The execution context. Along with the parameters listed below, the context also contains objects that you describe as Requirements.

ctx.issue

Issue

The current ticket.

ctx.currentUser

User

The user who makes updates after which the SLA policy will be applied to this ticket.

Example

onEnter: (ctx) => { console.log('onEnter', ctx.issue.id); }

 

slaGuardFunction

slaGuardFunction(ctx, ctx.issue, ctx.currentUser)

This function is called to determine whether the SLA policy can be applied to a ticket. Only SLA policy scripts use this function.

Parameters

Name

Type

Description

ctx

Object

The execution context. Along with the parameters listed below, the context also contains objects that you describe as Requirements.

ctx.issue

Issue

The current ticket.

ctx.currentUser

User

The user who makes updates after which the SLA policy will be applied to this ticket.

Example

guard: (ctx) => { return false; }

 

Last modified: 15 March 2024