SpEL Built-in Functions
Introduction
This chapter is a complete reference to SpEL built-in functions—the ready-to-use helpers that are always at your fingertips while writing tSM expressions. You will find two kinds of helpers here:
-
Type extensions – methods that extend everyday data types such as strings, numbers, dates, lists, sets and maps. They read naturally:
'Hello'.uppercase() // "HELLO"
[1,2,3].sum() // 6 (example only) -
Standalone functions – utilities that are not tied to any specific value and are invoked with the
#prefix:#now() // current date-time
#randomUUID() // e.g. "8e29…"
#if(#total > 100).then('Large')...
All functions described in this chapter are available anywhere SpEL is evaluated—inside console experiments, mapping scripts, conditions, service calls, process gateways, and more. Use the tables below to scan each group quickly: signature in the first column, behavior in the second, plus compact examples at the end of every section.
1 String
| Method | Signature | Description |
|---|---|---|
| contains | (other :String, ignoreCase :Boolean =false): Boolean | Returns true when other is found inside the string. Set ignoreCase=true to ignore case. |
| startsWith | (other :String, ignoreCase :Boolean =false): Boolean | Returns true if the string begins with other. Case‑insensitive when ignoreCase is true. |
| isEmpty / isNotEmpty | (): Boolean | isEmpty is true when the string length is zero. isNotEmpty is the opposite. |
| isBlank / isNotBlank | (): Boolean | isBlank is true when the string is empty or consists solely of whitespace. isNotBlank is the opposite. |
| length | (): Int | Number of characters in the string. |
| lowercase / uppercase | (): String | Converts all alphabetic characters to lower/upper case. |
| padStart | (length :Int, padChar :Char =' '): String | Left‑pads the string with padChar until it reaches length. |
| replace | (oldValue :String, newValue :String): String | Returns a copy of the string with every occurrence of oldValue replaced by newValue. |
| toBoolean | (): Boolean | true when the string equals "true" (ignoring case), otherwise false. |
| toInt / toLong | (): Int / Long | Parses the string as a signed decimal number. Throws error if not numeric. |
| decodeBase64 | (): ByteArray | Decodes Base‑64 text into raw bytes. |
| toByteArray | (): ByteArray | Converts the string to a byte array using the default character set of the system. |
| toUuid | (): UUID | Converts a canonical UUID string into a UUID object. |
| toJsonNode | (): JsonNode | Parses JSON text and returns a tree model (JsonNode) for flexible navigation. |
| toJsonObject | (): Any | Parses JSON text into plain collections: objects → Map, arrays → List, primitives stay primitive. |
| toDate | (format :String): Date | Parses the string as a date/time using the supplied format pattern. |
(): Date | Parses the string as an ISO‑8601 date/time with offset. | |
| parse | (regexPattern :String): Map<String,String>? | Matches the string against regexPattern (may contain named groups). Returns a map of capture name → text, or null if no match. |
Examples
'+1 234'.parse("\\+(?<cc>\\d{1,3})\\s+(?<num>.*)")
// → {'cc':'1','num':'234'}
' '.isBlank() // true
'7'.padStart(3,'0') // '007'
2 List & Set
| Method | Signature | Description |
|---|---|---|
| forEach | (varRef, expr1, expr2, …): List | Iterates over each element, evaluating the expressions in the context of that element. The first argument must be a variable reference (e.g. #item). A special variable #index holds the position. The last expression’s value for each element is collected into the resulting list. |
| filter | (predicateExpr): List<T> | Keeps elements for which predicateExpr evaluates to true. Inside the predicate you can use it and index. |
| size / get / indexOf / first / last | see signature | Standard collection helpers. |
| distinct / distinctCount | (): List<T> / (): Map<T,Int> | Removes duplicates (distinct) or counts occurrences (distinctCount). |
| sorted / reversed / min / max | (): … | Returns a sorted copy, a reversed copy, or the minimum/maximum element using natural ordering. |
| take / drop / subList | … | Slice helpers: first n, skip n, or view [from,to) of the list. subList is backed by the original list. |
| zipWith | (other :List): Map<T,T2> | Combines two lists into a map where keys are elements of this list and values are elements at the same index of other. Stops at the shorter length. |
| minus | (other :Collection): List<T> | Returns a list containing all elements of this list except those also in other. |
| sum | (): Long | Returns a list containing all elements of this list except those also in other. |
Example
[1,2,3].forEach(#n, #n * #n).filter(#it > 2) // [4,9]
3 Map
| Method | Signature | Description |
|---|---|---|
| keys / values / size / isEmpty / containsKey / containsValue / get | – | Standard methods to iterate ma entries. |
| withRemovedKey / withRemovedKeys | (key): Map / (keys :List): Map | Returns a copy of the map with the specified key or keys removed. |
| withRemovedKeysRecursive | (keys :List): same type | Returns a deep copy of the structure with any entry whose key equals one in keys removed, searching through nested lists and maps. |
| withReplacedValuesRecursive | (key :String, oldVal, newVal): same type | Recursively replaces a property named key whose current value equals oldVal with newVal. |
Example
{"a": "A", "b": "B"}.keys() // ["a", "b"]
4 Date
| Method | Signature | Description |
|---|---|---|
| iso | (): String | Formats the date as ISO 8601 with milliseconds in the UTC timezone. |
| formatted | (pattern :String, zone :String?=null): String | Formats the date using the given pattern. If zone is provided, the date is first adjusted to that timezone. |
| isBefore / isAfter | (other :Date): Boolean | Compares two dates. |
| setTime | (hours, minutes, seconds, zone): Date | Returns a new date equal to the original date but with the specified time of day in the specified timezone. |
| setMidnight | (): Date | Returns a new date set to midnight (00:00:00) in the CET timezone. |
| plus/minus Seconds/Minutes/Hours | (n :Int): Date | Adds or subtracts the specified amount of time units. |
| plusDuration / minus | (isoDuration :String): Date | Adds or subtracts an ISO‑8601 duration (e.g. "PT90M"). If the receiver is null, the current moment is used. |
| addIntervalPercentage | (dateTo :Date, percent :Long): Date | Calculates a date that lies percent % of the interval beyond dateTo relative to the receiver. |
| startOfMonth / endOfMonth / startOfYear / endOfYear | (): Date | Returns the first or last moment of the month or year containing the date. |
5 Number
| Method | Signature | Description |
|---|---|---|
| toString | (): String | Converts the number to its string representation. |
| toDate | (): Date | Interprets the number as a Unix timestamp. Values greater than 2 147 483 647 are treated as milliseconds; smaller values are treated as seconds. |
6 Byte Array
| Method | Signature | Description |
|---|---|---|
| encodeBase64 | (): String | Encodes the byte array as Base‑64 text. |
8 Hash‑prefixed standalone helpers
| Method | Signature | Description |
|---|---|---|
| #do | #do(expr1, expr2, …): Any | Evaluates several expressions in order and returns the last result. All evaluated values share the same local context. |
| #with | #with(expr1, …).do(finalExpr) | Lets you define variables (and other expressions) in #with, then evaluate a final expression inside .do. The variables declared in #with are visible only inside the .do block. |
| #if / .then / .elseif / .else | – | Fluent multi‑branch conditional. Each .then() block is evaluated only if the preceding condition is met. |
| #case | #case().when(condition, expr).else(expr) | Checks each condition in order; the first one that evaluates to a "truthy" value triggers its expression. |
| #match | #match(value).when(matchVal, expr).else(expr) | Similar to a switch statement: compares value to each matchVal for equality. |
| #try / .catch | – | Evaluates expressions and, if any throw an exception, executes the .catch block. The caught exception instance is available inside .catch as #error. |
| #currentUser | (): UUID | Returns the UUID of the user on whose behalf the script runs. |
| #now | (): Date | Current date/time (UTC). |
| #randomTrueFalse | (): Boolean | Returns true or false with equal probability. |
| #randomUUID | (): UUID | Generates a random UUID. |
| #uuid | (text :String): UUID | Converts a canonical UUID string into a UUID object. |
| #businessException | (code :String, msg :String): Nothing | Throws a business‑level exception with the given code and message. |
| #isNotEmpty | (value): Boolean | Returns true if value is neither null, an empty string, nor the string "null". |
| #isNullOrEmpty | (value): Boolean | Returns true when value is null, an empty string, or the string "null". |
| #jsonToString | (obj): String | Serialises an object into its JSON text representation. |
| #objectToMap | (obj): Map | Converts an arbitrary object (including complex JSON trees) into nested Map / List collections for easier SpEL manipulation. |