07_SpEL_builtin_functions.md

sidebar_position	7
id	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:

1. 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)
   

2. 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.