Statements

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

Statements by Type
rule-specific statements	control flow	iterations	warnings and errors

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. The allowed transitions for each value are displayed in the drop-down for the custom field even when you have a guard condition that potentially blocks the selection of the value. If the guard conditions is not met, the selection is ignored. There are no mechanisms for exposing this condition to users. If you add guard conditions to your statements, make sure your users are aware of the restrictions that are applied by the workflow.
`in`	Defines 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.
Parameters	`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