YouTrack Standalone 2017.1 Help

String, Date, and Period Operations

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

String Operations
Date Operations
Period Operations

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.

/help/img/youtrack/2017.1/workflowEditorStringOperations_thumbnail.png

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
DescriptionChecks whether the preceding string is empty ("") or null.
isNotEmpty(): Boolean
DescriptionChecks whether the preceding string is not empty ("") and not null.
isBlank(): Boolean
DescriptionChecks whether the preceding string is whitespace, empty ("") or null.
isNotBlank(): Boolean
DescriptionChecks whether the preceding string is not whitespace, not empty ("") and not null.
trim(enum side[both, start, end], enum mode[asis, blankToNull, nullToEmpty]): string
ParameterssideDetermines which side of the string is trimmed.
modeDetermines how to handle blank and null values.
DescriptionRemoves whitespace from the beginning, end, or both sides of a string. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParametersthatThe string to compare to the preceding string.
ignoreCaseDetermines whether the comparison is case sensitive.
DescriptionChecks whether a string matches a specified string. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParameterssearchStrThe string to find in the preceding string.
startPosSets the starting position inside the string.
lastDetermines whether to search from the start or end of the string.
DescriptionFinds an index within a string. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParameterssearchStrThe string to find in the preceding string.
ordinalThe n-th searchStr to find.
DescriptionFinds an ordinal index within a string.
contains(string searchStr, flag ignoreCase): Boolean
ParameterssearchStrThe search string to find in the preceding string.
ignoreCaseDetermines whether the comparison is case sensitive.
DescriptionChecks if a string contains a search string. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParameterssearchStrThe search characters to find in the preceding string.
modeDetermines whether to find any, none, or only the specified characters.
DescriptionChecks if a string contains a search character. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParametersstartThe position to start from. A negative integer counts back from the end of the string.
endThe position to end at (exclusive). A negative integer counts back from the end of the string.
DescriptionGets a substring from the specified string avoiding exceptions. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParameterslengthThe length of the required string.
fromPositionThe position to start from. A negative integer is treated as zero.
sideDetermines whether the string is taken from the left, middle, or right side of the string.
DescriptionReturns a substring of a specified length from the preceding string. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParametersseparatorThe string to search for.
posThe position to start from. A negative integer is treated as zero.
lastDetermines whether to search for the first or last occurrence of the separator.
DescriptionChecks whether a string contains a specified substring relative to a specified separator. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParametersopenThe string before the substring.
closeThe string after the substring.
DescriptionReturns a string that is nested in between two strings. Only the first match is returned.
split([string separator], [int max], flag preserveAllTokens): sequence<string>
ParametersseparatorThe character to use as a delimiter.
maxThe maximum number of elements to include in the sequence. A zero or negative value implies no limit.
preserveAllTokensDetermines whether adjacent separators are treated as separators for empty tokens.
DescriptionSplits a string into a sequence. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[preserveAllTokens: false]split()Splits the string into a sequence, using whitespace as the separator.
(string: const "") [preserveAllTokens: true]splitByWholeSeparatorPreserveAllTokensSplits 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]splitByWholeSeparatorSplits 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]splitByWholeSeparatorSplits 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]splitByWholeSeparatorPreserveAllTokensSplits 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]splitByWholeSeparatorPreserveAllTokensSplits 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
ParametersremoveThe string to remove from the preceding string.
ignoreCaseDetermines whether the comparison is case sensitive.
sideDetermines whether to search from the start or end of the preceding string.
DescriptionRemoves all occurrences of a substring from within the source string. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParameterssearchStringThe string to find in the preceding string.
replacementThe string to replace the searchString with.
maxThe maximum number of values to replace.
DescriptionReplaces all occurrences of a string within another string. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
string: searchString, string: replacementreplace(string: searchString, string: replacement)Replaces a string with another string inside a larger string.
string: searchString, string: replacement, int: maxreplace(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
ParameterssearchCharsThe characters to find in the preceding string.
replaceCharsThe characters to replace the searchChars with.
DescriptionReplaces multiple characters in a string in one go. This method can also be used to delete characters.
chomp(): string
DescriptionRemoves a new line from the end of a string, if present.
repeat(int times): string
ParameterstimesThe number of times to repeat the preceding string.
DescriptionRepeat a string times number of times to form a new string.
align(int size, [string padStr], enum to[left, right, center]): string
ParameterssizeSpecified the length of the new string.
padStrDetermines which characters are added to the preceding string.
toDetermines which part of the string the padStr characters are added to.
DescriptionAlign a string to the specified length. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
(int: size) [to: left]rightPadRight 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]leftPadLeft 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]centerCenters 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
DescriptionGets a the length of a string or 0 if the string is null.
upperCase(): string
DescriptionConverts a string to upper case.
lowerCase(): string
DescriptionConverts a string to lower case.
capitalize(): string
DescriptionCapitalizes a string, changing the first letter to title case.
uncapitalize(): string
DescriptionUncapitalizes a string, changing the first letter to lower case. No other letters are changed.
is(flag alpha, flag space, flag numeric): Boolean
ParametersalphaDetermines whether to search for alphabetic characters.
spaceDetermines whether to search for space characters.
numericDetermines whether to search for numeric characters.
DescriptionChecks a string for specific characters. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
DescriptionChecks if the string contains only ASCII printable characters.
default([string defaultString], flag ifEmpty): string
ParametersdefaultStringThe default string to return if the input is null.
ifEmptyDetermines how to handle blank values.
DescriptionReturns 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
ParametersOperationDescription
[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
ParametersmaxWidthThe maximum length of the result string. Must be a value of 4 or higher.
offsetThe left edge of the source string.
DescriptionAbbreviates a string using ellipses. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
(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
ParameterstargetThe string to compare to the preceding string.
DescriptionFinds the Levenshtein distance between the preceding string and a target string.
startsWith(string prefix, flag ignoreCase): Boolean
ParametersprefixThe string to find at the start of the preceding string.
ignoreCaseDetermines whether the comparison is case sensitive.
DescriptionCheck if a string starts with a specified prefix. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParameterssuffixThe string to find at the end of the preceding string.
ignoreCaseDetermines whether the comparison is case sensitive.
DescriptionCheck if a string ends with a specified suffix. The parameters determine which of the following operations is performed.
Operations
ParametersOperationDescription
[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
ParametersformatThe format to apply to the preceding date value.
DescriptionApplies 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
DescriptionReturns 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
ParametersfieldNameThe name of a custom field that stores a period type.
DescriptionReturns the value that is stored in the specified custom field. Returns the value in minutes as an integer.
getPeriodFieldOldValueInMinutes(string fieldName): integer
ParametersfieldNameThe name of a custom field that stores a period type.
DescriptionReturns 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
ParametersfieldNameThe name of a custom field that stores a period type.
valueThe value in minutes to assign to the specified custom field.
DescriptionAssigns a value to the specified custom field.

See Also

Last modified: 18 April 2017