YouTrack Standalone 2017.2 Help

Statements

YouTrack workflow language supports several standard iterative and conditional statements. These statements function as expected as in other structured programming languages.

The syntax for statements is similar to JavaScript.

  • A single statement may span multiple lines.

  • Each statement is separated by a semicolon.

  • Multiple statements may occur on a single line if each statement is separated by a semicolon.

Block statements group one or more statements. The block is delimited by a pair of braces.

Rule-specific Statements

Workflow rules use a pre-defined set of conditional statements. These statements determine when changes are applied to an issue and introduce block statements that determine which changes are applied.

Statement

Description

when

Defines an initial guard condition for a stateless rule.

[schedule]Defines the schedule for executing a scheduled rule. The following intervals are supported:
  • every minute

  • daily at <hour>:<minute>:<second>

  • weekly on <day of week> at <hour>:<minute>:<second>

  • hourly at <minute>:<second>

  • monthly on <day of month> at <hour>:<minute>:<second>

  • yearly on <month>, <day of month> at <hour>:<minute>:<second>

  • cron: [cron expression]

enter

Introduces a set of changes to apply to an issue in a state-machine rule. The changes that are specified in a nested block statement are applied when the field is set to the specified value.

exit

Introduces a set of changes to apply to an issue in a state-machine rule. The changes that are specified in a nested block statement are applied when the field is changed from the specified value.

on

Defines the action that is associated with a value in a state-machine rule.
  • The changes that are specified in the following do element are applied when the action is applied with a command or the field is set to the specified value.

  • The optional [condition] stores a guard condition. Here, you can insert a Boolean expression that applies the changes if it resolves to the value true.

  • The do element introduces a set of changes that are applied if the previous condition is met. These changes are specified in a nested {statements} block.

  • After the changes are applied, the issue transitions automatically to the value that is specified in the transit to declaration.

inDefines the time frame that is associated with a value in a state-machine rule.
  • The changes that are specified in the following do element are applied after the specified time frame.

  • The optional [condition] stores a guard condition. Here, you can insert a Boolean expression that applies the changes if it resolves to the value true.

  • The do element introduces a set of changes that are applied if the previous condition is met. These changes are specified in a nested {statements} block.

  • After the changes are applied, the issue transitions automatically to the value that is specified in the transit to declaration.

For examples, see Workflow Rules.

Control Flow

The following control flow statements are supported.

Statement

Description

if

Executes a statement if a specified condition is true.

else

Executes a statement when none of the previous statements are true.

else if

Executes a statement when the specified condition in a preceding if statement is false.

break

Terminates the current loop, switch, or label statement and transfers program control to the statement following the terminated statement.

continue

Terminates execution of the statements in the current loop and continues execution of the loop with the next iteration.

The following example from the default workflows illustrates how to use a control flow statement in a workflow.

var user; if (issue.Assignee == null) { user = issue.project.leader; } else { user = issue.Assignee; }

In this example, the if statement assigns an issue and sets the value of the user variable to the project leader when the value for the Assignee field is not set. If the issue has already been assigned to another user, the else statement sets the value of the user variable to the current assignee.

Iterations

The following statements can be used to iterate over a sequence of elements.

Statement

Description

while

Creates a loop that executes a specified statement as long as the test condition evaluates to true. The condition is evaluated before executing the statement.

for

Creates a loop that consists of three optional expressions, enclosed in parentheses and separated by semicolons, followed by a statement executed in the loop.

for each

Iterates a specified variable over all values of object's properties. For each distinct property, a specified statement is executed.

When you iterate over a collection with a for each statement, you define an arbitrary variable that references the elements in the sequence in the statement itself.

The following examples from the default workflows illustrate how to use iterations in workflows.

var duplicatedBy = is duplicated by; for each duplicate in duplicatedBy { if (duplicate.project == project) { duplicate.Fixed in build = Fixed in build; } }

In this example, the for each statement checks the sequence of issues with the duplicatedBy link type. If the project property of any issue in the sequence matches the current project, the value of the Fixed in build is set.

The variable duplicatedBy represents the sequence of issues that are linked to the current issue with the link name is duplicated by. Each issue in the sequence is assigned the variable name duplicate.

for each duplicatedIssue in duplicates { if (duplicatedIssue.project == project && duplicatedIssue.Fixed in build != null) { Fixed in build = duplicatedIssue.Fixed in build; break; } }

In this example, the for each statement checks the sequence of issues with the duplicates link type. If the project property of any issue in the sequence matches the current project and the current value of the Fixed in build is not null, the value of the Fixed in build is set.

In this example, the sequence of issues that are linked to the current issue have the link name duplicates. Each issue ini the sequence is assigned the variable name duplicatedIssue.

Warnings and Errors

The following statements display errors or warnings to the user and write messages to the log files in YouTrack.

assert [condition: Boolean]: (string)

Parameters

[condition]

A Boolean expression.

string

The warning text to display on the user interface.

Description

Verifies that a Boolean expression is true. If it is not true, the system throws an error. All changes are rolled back to the initial state. If a workflow rule changes the properties of an issue to match the condition for executing a second workflow rule, changes are applied by the second workflow. This chain of events continues until all of the relevant statements have been executed. All of the changes are applied in a single transaction. When an assert statement returns a false value, all of the changes are rolled back.

Example

assert dep.State.isResolved: l10n ( The issue has unresolved dependencies and thus cannot be set Fixed! );

message(string)

Parameters

string: The text to display on the user interface.

Description

Displays the specified string of text at the top of the page in YouTrack when the specified condition is met.

Example

message("Hello! You are logged in as " + loggedInUser.fullName);

debug(string)

Parameters

string: The text to write to the log file.

Description

Writes the specified string of text in the worklfow.log and youtrack.log files.

Example

debug("The number: "+ number);

info(string)

Parameters

string: The text to write to the log file.

Description

Writes the specified string of text in the worklfow.log and youtrack.log files.

Example

info("March 8? - " + (now != 2013-03-08));

warn(string)

Parameters

string: The text to write to the log file.

Description

Writes the specified string of text in the worklfow.log and youtrack.log files.

Example

warn("Logged in user is developer: " + loggedInUser.isInGroup("Developers"));

error(string)

Parameters

string: The text to write to the log file.

Description

Writes the specified string of text in the worklfow.log, youtrack.log, and errors.log files.

Example

error("Now: " + now.format(fullDate));

fatal(string)

Parameters

string: The text to write to the log file.

Description

Writes the specified string of text in the worklfow.log, youtrack.log, and errors.log files.

Example

fatal((issue.created == null) + "");
Last modified: 7 March 2019