sidebar_position	id
7	spel-built-in-functions

SpEL Built-in Functions reference

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.

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.

edudant/07_SpEL_builtin_functions.md