String, Date, and Period Operations

The YouTrack workflow language supports several string and date operations that are used in standard Java libraries.

String Operations
isEmpty isNotEmpty isBlank isNotBlank trim	eq indexOf ordinalIndexOf contains containsChars	substring substringOfLength substringRelative substringBetween split	remove replace replaceChars chomp repeat	align length upperCase lowerCase capitalize	uncapitalize is isAsciiPrintable default abbreviate	getLevenshteinDistance startsWith endsWith

Date Operations
format	millis

Period Operations
getPeriodFieldValueInMinutes	getPeriodFieldOldValueInMinutes	setPeriodFieldValueInMinutes

The syntax for these operations is applied differently from other programming languages. When you want to use an operation, simply write the operation after the method or property that returns the appropriate data type. The syntax for each operation is presented in the format: [name]([data type] parameter): [data type].

The workflow editor applies constraints that let you enter only parameters and options that are supported by the workflow programming language. With code completion, the workflow editor displays a description and the available parameters for each operation.

workflowEditorStringOperations thumbnail

The following example demonstrates how to use an operation in a workflow rule.

var extractedUsername = comments.added.first.text.substringBetween("@", " ");
project.getUser(extractedUsername).notify("[Youtrack, Comment notice]", "You were mentioned in the comment of issue " + "", true);

This rule extracts the login for a user who is mentioned in comment from the @username substring and sends a notification to the mentioned user.

String Operations

The following operations can be used with fields, methods, and operations that return a string data type.

isEmpty(): Boolean
Description	Checks whether the preceding string is empty ("") or null.

isNotEmpty(): Boolean
Description	Checks whether the preceding string is not empty ("") and not null.

isBlank(): Boolean
Description	Checks whether the preceding string is whitespace, empty ("") or null.

isNotBlank(): Boolean
Description	Checks whether the preceding string is not whitespace, not empty ("") and not null.

trim(enum side[both, start, end], enum mode[asis, blankToNull, nullToEmpty]): string

Parameters

side

Determines which side of the string is trimmed.

mode

Determines how to handle blank and null values.

Description

Removes whitespace from the beginning, end, or both sides of a string. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[side: both, mode: asis]	strip()	Strips whitespace from the start and end of a string.
[side: both, mode: blankToNull]	stripToNull()	Strips whitespace from the start and end of a string. If the string is empty ("") after the operation, returns a null value.
[side: both, mode: nullToEmpty]	stripToEmpty()	Strips whitespace from the start and end of a string. If the input string is null, returns an empty string
[side: start, mode: asis]	stripStart(string: const null)	Strips any of a set of characters from the start of a string.
[side: end, mode: asis]	stripEnd(string: const null)	Strips any of a set of characters from the end of a string.

eq(string that, flag ignoreCase): Boolean

Parameters

that

The string to compare to the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

Description

Checks whether a string matches a specified string. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[ignoreCase: false]	equals(string: that)	Checks whether a string matches a specified string. The comparison is case sensitive.
[ignoreCase: true]	equalsIgnoreCase(string: that)	Checks whether a string matches a specified string, ignoring case.

indexOf(string searchStr, [int startPos], flag last): integer

Parameters

searchStr

The string to find in the preceding string.

startPos

Sets the starting position inside the string.

last

Determines whether to search from the start or end of the string.

Description

Finds an index within a string. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[last: false]	indexOf(string: searchStr)	Finds the first index within a string, handling null.
[int: startPos, last: false]	indexOf(string: searchStr, int: startPos)	Finds the first index within a string from a start position, handling null.
[last: true]	lastIndexOf(string: searchStr)	Finds the last index within a string, handling null.
[int: startPos, last: true]	lastIndexOf(string: searchStr, int: startPos)	Finds the last index within a string from a start position, handling null.

ordinalIndexOf(string searchStr, int ordinal): integer
Parameters	`searchStr`	The string to find in the preceding string.
Parameters	`ordinal`	The n-th `searchStr` to find.
Description	Finds an ordinal index within a string.

contains(string searchStr, flag ignoreCase): Boolean

Parameters

searchStr

The search string to find in the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

Description

Checks if a string contains a search string. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[ignoreCase: false]	contains(string: searchStr)	Checks if a string contains a search string, handling null. The comparison is case sensitive.
[ignoreCase: true]	containsIgnoreCase(string: searchStr)	Checks if a string contains a search string, ignoring case, handling null.

containsChars(string searchStr, enum mode[any, none, only]): Boolean

Parameters

searchStr

The search characters to find in the preceding string.

mode

Determines whether to find any, none, or only the specified characters.

Description

Checks if a string contains a search character. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[mode: any]	containsAny(string: searchStr)	Checks if the string contains any character in the given set of characters.
[mode: none]	containsNone(string: searchStr)	Checks that the string does not contain certain characters.
[mode: only]	containsOnly(string: searchStr)	Checks if the string contains only certain characters.

substring(int start, [int end]): string

Parameters

start

The position to start from. A negative integer counts back from the end of the string.

end

The position to end at (exclusive). A negative integer counts back from the end of the string.

Description

Gets a substring from the specified string avoiding exceptions. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[int: start]	substring(int: start)	Gets a substring from the specified string avoiding exceptions. A negative start position can be used to start `start` number of characters from the end of the string.
[int: start, int: end]	substring(int: start, int: end)	Gets a substring from the specified string avoiding exceptions. A negative start position can be used to start `start` number of characters from the end of the string. The returned substring starts with the character in the `start` position and ends before the `end` position. Position counting is zero-based.

substringOfLength(int length, [int fromPosition], enum side[left, mid, right]): string

Parameters

length

The length of the required string.

fromPosition

The position to start from. A negative integer is treated as zero.

side

Determines whether the string is taken from the left, middle, or right side of the string.

Description

Returns a substring of a specified length from the preceding string. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[side: left]	left(int: length)	Gets the leftmost `length` characters of a string.
[side: right]	right(int: length)	Gets the rightmost `length` characters of a string.
[int: fromPosition, side: mid]	mid(int: length, int: fromPosition)	Gets the `length` characters from the middle of a string starting from the specified position.

substringRelative(string separator, enum pos[before, after], flag last): string

Parameters

separator

The string to search for.

pos

The position to start from. A negative integer is treated as zero.

last

Determines whether to search for the first or last occurrence of the separator.

Description

Checks whether a string contains a specified substring relative to a specified separator. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[pos: after, last: false]	substringAfter(string: separator)	Returns the substring after the first occurrence of a separator. The separator is not returned.
[pos: after, last: true]	substringAfterLast(string: separator)	Returns the substring after the last occurrence of a separator. The separator is not returned.
[pos: before, last: false]	substringBefore(string: separator)	Returns the substring before the first occurrence of a separator. The separator is not returned.
[pos: before, last: true]	substringBeforeLast(string: separator)	Returns the substring before the last occurrence of a separator. The separator is not returned.

substringBetween(string open, string close): string
Parameters	`open`	The string before the substring.
Parameters	`close`	The string after the substring.
Description	Returns a string that is nested in between two strings. Only the first match is returned.

split([string separator], [int max], flag preserveAllTokens): sequence<string>

Parameters

separator

The character to use as a delimiter.

max

The maximum number of elements to include in the sequence. A zero or negative value implies no limit.

preserveAllTokens

Determines whether adjacent separators are treated as separators for empty tokens.

Description

Splits a string into a sequence. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[preserveAllTokens: false]	split()	Splits the string into a sequence, using whitespace as the separator.
(string: const "") [preserveAllTokens: true]	splitByWholeSeparatorPreserveAllTokens	Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as separators for empty tokens.
(string: separator) [preserveAllTokens: false]	splitByWholeSeparator	Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as one separator.
(string: separator, int: max) [preserveAllTokens: false]	splitByWholeSeparator	Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as one separator. Returns a maximum of `max` substrings.
(string: separator) [preserveAllTokens: true]	splitByWholeSeparatorPreserveAllTokens	Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as separators for empty tokens.
(string: separator, int: max) [preserveAllTokens: true]	splitByWholeSeparatorPreserveAllTokens	Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as separators for empty tokens. Returns a maximum of `max` substrings.

remove(string remove, flag ignoreCase, enum side[start, end]): string

Parameters

remove

The string to remove from the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

side

Determines whether to search from the start or end of the preceding string.

Description

Removes all occurrences of a substring from within the source string. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[ignoreCase: false, side: start]	removeStart(string: remove)	Removes a substring only if it is at the beginning of a source string, otherwise returns the source string. The comparison is case sensitive.
[ignoreCase: true, side: start]	removeStartIgnoreCase(string str, string remove)	Case insensitive removal of a substring if it is at the beginning of a source string, otherwise returns the source string.
[ignoreCase: false, side: end]	removeEnd(string str, string remove)	Removes a substring only if it is at the end of a source string, otherwise returns the source string. The comparison is case sensitive.
[ignoreCase: true, side: end]	removeEndIgnoreCase(string str, string remove)	Case insensitive removal of a substring if it is at the end of a source string, otherwise returns the source string.

replace(string searchString, string replacement, [int max]): string

Parameters

searchString

The string to find in the preceding string.

replacement

The string to replace the searchString with.

max

The maximum number of values to replace.

Description

Replaces all occurrences of a string within another string. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
string: searchString, string: replacement	replace(string: searchString, string: replacement)	Replaces a string with another string inside a larger string.
string: searchString, string: replacement, int: max	replace(string: searchString, string: replacement, int: max)	Replaces a string with another string inside a larger string, for the first `max` values of the search string.

replaceChars(string searchChars, string replaceChars): string
Parameters	`searchChars`	The characters to find in the preceding string.
Parameters	`replaceChars`	The characters to replace the `searchChars` with.
Description	Replaces multiple characters in a string in one go. This method can also be used to delete characters.

chomp(): string
Description	Removes a new line from the end of a string, if present.

repeat(int times): string
Parameters	`times`	The number of times to repeat the preceding string.
Description	Repeat a string `times` number of times to form a new string.

align(int size, [string padStr], enum to[left, right, center]): string

Parameters

size

Specified the length of the new string.

padStr

Determines which characters are added to the preceding string.

to

Determines which part of the string the padStr characters are added to.

Description

Align a string to the specified length. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
(int: size) [to: left]	rightPad	Right pad a string in a larger string of size `size` using the space character (' ').
(int: size, string: padStr) [to: left]	rightPad(string padStr)	Right pad a string in a larger string of size `size`. Uses a supplied string as the value to pad the string with.
(int: size) [to: right]	leftPad	Left pad a string in a larger string of size `size` using the space character (' ').
(int: size, string: padStr) [to: right]	leftPad(string padStr)	Left pad a string in a larger string of size `size`. Uses a supplied string as the value to pad the string with.
(int: size) [to: center]	center	Centers a string in a larger string of size `size` using the space character (' ').
(int: size, string: padStr) [to: center]	center(string padStr)	Centers a string in a larger string of size `size`. Uses a supplied string as the value to pad the string with.

length(): integer
Description	Gets a the length of a string or 0 if the string is null.

upperCase(): string
Description	Converts a string to upper case.

lowerCase(): string
Description	Converts a string to lower case.

capitalize(): string
Description	Capitalizes a string, changing the first letter to title case.

uncapitalize(): string
Description	Uncapitalizes a string, changing the first letter to lower case. No other letters are changed.

is(flag alpha, flag space, flag numeric): Boolean

Parameters

alpha

Determines whether to search for alphabetic characters.

space

Determines whether to search for space characters.

numeric

Determines whether to search for numeric characters.

Description

Checks a string for specific characters. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[alpha: false, space: false, numeric: true]	isNumeric()	Checks if the string contains only unicode digits. A decimal point is not a unicode digit and returns false.
[alpha: false, space: true, numeric: false]	isWhitespace()	Checks if the string contains only whitespace.
[alpha: false, space: true, numeric: true]	isNumericSpace()	Checks if the string contains only unicode digits or space (' '). A decimal point is not a unicode digit and returns false.
[alpha: true, space: false, numeric: false]	isAlpha()	Checks if the string contains only unicode letters.
[alpha: true, space: false, numeric: true]	isAlphanumeric()	Checks if the string contains only unicode letters or digits.
[alpha: true, space: true, numeric: false]	isAlphaSpace()	Checks if the string contains only unicode letters and space (' ').
[alpha: true, space: true, numeric: true]	isAlphanumericSpace()	Checks if the string contains only unicode letters, digits or space (' ').

isAsciiPrintable(): Boolean
Description	Checks if the string contains only ASCII printable characters.

default([string defaultString], flag ifEmpty): string

Parameters

defaultString

The default string to return if the input is null.

ifEmpty

Determines how to handle blank values.

Description

Returns either the current string, an empty string, or the value of a default string. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[ifEmpty: false]	defaultString()	Returns either the passed in string, or if the string is null, an empty string ("").
(string: defaultString) [ifEmpty: false]	defaultString(string: defaultStr)	Returns either the passed in string, or if the string is null, the value of defaultStr.
(string: defaultString) [ifEmpty: true]	defaultIfEmpty(string defaultString)	Returns either the passed in string, or if the string is empty or null, the value of defaultStr.

abbreviate(int maxWidth, [int offset]): string

Parameters

maxWidth

The maximum length of the result string. Must be a value of 4 or higher.

offset

The left edge of the source string.

Description

Abbreviates a string using ellipses. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
(int: maxWidth)	abbreviate(int: maxWidth)	Abbreviates a string using ellipses.
(int: offset, int: maxWidth)	abbreviate(int: offset, int: maxWidth)	Abbreviates a string using ellipses with a "left edge" offset.

getLevenshteinDistance(string target): integer
Parameters	`target`	The string to compare to the preceding string.
Description	Finds the Levenshtein distance between the preceding string and a target string.

startsWith(string prefix, flag ignoreCase): Boolean

Parameters

prefix

The string to find at the start of the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

Description

Check if a string starts with a specified prefix. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[ignoreCase: false]	startsWith(string: prefix)	Checks if a string starts with a specified prefix.
[ignoreCase: true]	startsWithIgnoreCase(string: prefix)	Case insensitive check if a string starts with a specified prefix.

endsWith(string suffix, flag ignoreCase): Boolean

Parameters

suffix

The string to find at the end of the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

Description

Check if a string ends with a specified suffix. The parameters determine which of the following operations is performed.

Operations

Parameters	Operation	Description
[ignoreCase: false]	endsWith(string: suffix)	Checks if a string ends with a specified suffix.
[ignoreCase: true]	endsWithIgnoreCase(string: suffix)	Case insensitive check if a string ends with a specified suffix.

Date Operations

The following operation can be used with fields, methods, and operations that return a date data type.

format(string format): string
Parameters	`format`	The format to apply to the preceding date value.
Description	Applies the specified UTC format to the date value. Returns a string. You can select a pre-defined date format or enter a custom format. Custom date formats start with `#` and specify date values with the variables `y`, `M`, `d`, and so on.

The difference between two fields with date data types is returned as a duration. The following operation can be used with an operation that returns a duration data type.

millis(): long
Description	Returns the the number of milliseconds in a duration as a long number.

Period Operations

The following operations can be used with fields that return a period data type.

getPeriodFieldValueInMinutes(string fieldName): integer
Parameters	`fieldName`	The name of a custom field that stores a period type.
Description	Returns the value that is stored in the specified custom field. Returns the value in minutes as an integer.

getPeriodFieldOldValueInMinutes(string fieldName): integer
Parameters	`fieldName`	The name of a custom field that stores a period type.
Description	Returns the previous value that was stored in the specified custom field before the changes that are applied in the current transaction. Returns the value in minutes as an integer.

setPeriodFieldValueInMinutes(string fieldName, int value): void
Parameters	`fieldName`	The name of a custom field that stores a period type.
Parameters	`value`	The value in minutes to assign to the specified custom field.
Description	Assigns a value to the specified custom field.

Last modified: 7 March 2019

YouTrack Standalone 2017.2 Help

String, Date, and Period Operations

String Operations

Date Operations

Period Operations

See Also

Concepts: