Simple - Built-in Functions

Available as of Camel 4.21

The simple language, has many built-in functions, and each of them take different set of parameters, and some are more advanced than others, for example the functions working with JSon or XML payloads. Regards of that, you may have need for being able to easily specify that the function should return the value as an integer instead of what it would otherwise do. To make this easy we have built-in a fixed set of very common result types to make this easy.

You do this by prefixing the function with any of the above, such as ${int:header.age} to return the age header as an integer. If you use XML then the XPath function can do this as well such as ${int:xpath(//food/quantity)}.

If you need to use a type that is not in the table above, then you can combine two functions together with the ${convertTo(type)} function, as follows:

${xpath(//food[name='food1']/price/text())} ~> ${convertTo(java.math.BigDecimal)}

The Camel functions are as the name implies specific to Apache Camel and these functions are primary used to access Camel functionality and content of the message being routed.

The core functions are powerful to give easy access to the current Exchange / Message being routed so you can get the message body, headers, variables and exchange properties.

The body function returns the message body as-is. If the body is a String with value Hello World, then ${body} returns Hello World.

The bodyAs function converts the body to the given type. For example if the body is the integer 42, then ${bodyAs(String)} returns "42" as a String. And ${mandatoryBodyAs(Integer)} will throw an exception if the body is null, otherwise it converts and returns the value.

The bodyOneLine function converts the body to a String and removes all line-breaks, so the string is in one line. This is useful for logging.

The bodyType function returns the Java class of the message body. For example if the body is "Hello", then the type is java.lang.String.

The convertTo function converts the message body (or a given expression) to the specified type. For example ${convertTo(int)} converts the body to an Integer, and ${convertTo(byte[])} converts to a byte array. You can also convert a nested expression: ${convertTo(${body},String)}.

The headerAs function returns a header value converted to the given type. For example if a header num contains the string "42", then ${headerAs(num,Integer)} returns the integer 42.

The variableAs function works similarly for variables. If a variable num contains "99", then ${variableAs(num,Integer)} returns the integer 99.

The exchangeProperty function returns an exchange property. You can use dot, colon, or bracket notation: ${exchangeProperty.color}, ${exchangeProperty:color}, or ${exchangeProperty[color]} all return the same value.

The setHeader function sets a message header from an expression. For example ${setHeader(foo,${body})} sets the header foo to the current body. You can also specify a type: ${setHeader(bar,int,${body})} converts the body to an Integer before setting the header. Setting a header to null removes it: ${setHeader(bar,${null})}.

The setVariable function works the same as setHeader but for exchange variables. For example ${setVariable(count,$\{body.length})} stores the body length in a variable named count, which can later be used as ${variable.count}.

The val function returns its argument as a constant value (unchanged). For example ${val(abc)} returns the string abc. When using a nested function ${val(${body})}, it captures the current body value at evaluation time.

The kindOfType function returns a string describing the kind of a value. It returns one of: null, string, number, boolean, array, or object. For example ${kindOfType('Hello')} returns string, ${kindOfType(123)} returns number, and if the body is a List then ${kindOfType()} returns array.

During routing, you can use the LogEIP to write to the log, for example:

The length function calculates the payload size in bytes (if possible). This is calculated by (if necessary) converting the payload into String to use for determine the byte length. For example ${length('Hello World')} returns 11. For larger payloads, then when using stream caching the length is pre-computed and usually does not require to load the content into memory.

The throwException function is used for throwing an exception. For example ${throwException('Invalid order')} throws an IllegalArgumentException with the given message. You can also specify the exception type: ${throwException('Not found',java.io.FileNotFoundException)}.

The exchangeId function returns the unique identifier of the current exchange. This is commonly used for correlation in log messages: ${exchangeId} returns a value like ID-myhost-1234-1234567890-0-1.

The routeId function returns the id of the route currently processing the exchange. For example ${routeId} returns myRoute when the exchange is inside a route with routeId("myRoute"). The fromRouteId function returns the route id where the exchange was originally created, which can differ from routeId when the exchange has been forwarded to another route via direct or seda.

The exception.message function is commonly used in error handling to get the exception message. For example in an onException block you can log: "Failed: ${exception.message}". If an IllegalStateException("boom") was thrown, then ${exception.message} returns boom. Use ${exception.stacktrace} if you need the full stack trace.

The properties:key:default function looks up a property placeholder value from the Camel configuration. For example ${properties:myApp.greeting} returns the value of the myApp.greeting property. You can also specify a default value: ${properties:myApp.greeting:Hello} returns Hello if the property is not set. And ${propertiesExist:myApp.greeting} returns true or false depending on whether the property exists.

The headers function returns all message headers as a java.util.Map. This is useful when you need to pass all headers to a bean or processor. The ${headers.size} returns the number of headers.

The messageTimestamp function returns the timestamp from the source system (e.g., Kafka, JMS) if available. This is different from the exchange created timestamp, as it reflects when the original event occurred. Returns 0 if no timestamp is available.

The array and list functions are less commonly used as they are more advanced and require to work with data that are structured in arrays or lists.

The collate function is used for grouping together data into smaller subgroups. Suppose you have a message body containing a list of 9 elements. Then by using ${collate(2)} will transform this into an java.util.Iterator that will return each sub list. As there are 9 elements as input then the output will be 5 sub lists with 2 2 2 2 and 1 element each.

The distinct function takes one or more values as input and then returns a Set with only the unique values. The input values can single objects or arrays or lists as well. If no values is provided then the ${distinct()} function will use the message body as input. For example ${distinct('Z','X','Z','A','B','A','C','D','B','E')} will return a Set with values [Z, X, A, B, C, D, E].

The forEach function is like a for loop that loops the input values and apply the function to each item, and aggregates their responses into a List as result.

For example suppose the message body contains a comma separated String with Camel,World,Cheese then executing ${forEach(${body},'Hello ${body}')} will return a List with 3 values: ["Hello Camel", "Hello World", "Hello Cheese"].

The list function is used for taking all input values and putting them into a single List as response. For example if the message body contains '4' then ${list(1,2,3,${body})} will return a list with 4 elements. [1,2,3,4].

You can also add and remove from java.util.List(s). For example if the message body is a List then you can add something ${listAdd('Hello')}. This will add to the message body. The source can also be an expression instead of the message body, such as a variable: ${listAdd(${variable.myVar},'Hello')}. To remove from a list, you use ${listRemove('Hello')}, or use a number to refer to the position ${listRemove(0)}. Use last as a special index to remove the last element: ${listRemove(last)}.

Besides adding to a List its also possible to add to a java.util.Map with the mapAdd function. For example if the message body is a Map then you can add something ${mapAdd('country','DK')}. This will add to the message body. The source can also be an expression instead of the message body, such as a variable: ${mapAdd(${variable.myVar},'country','DK')}. To remove from a list, you use ${mapRemove('country')}.

The map function is similar to the list function but for creating a Map instead where the values are grouped in pairs 2 by 2. For example ${map(1,a,2,b,3,c)} will return a map with 3 elements {1=a, 2=b, 3=c}.

The createEmpty function is for creating an empty object which can either be an empty String or a List, Map or Set. To create an empty Map use ${createEmpty(map)}.

The reverse function is to reverse the order of the values. For example ${reverse(1,2,3,4,5)} will return a List with the values 5,4,3,2,1.

And the shuffle function will randomize the order of the values. The sort function will sort the order of the values (in natural order A…​Z).

The size functions is used to determine the number of elements, when using Collection or array based payloads. If not then either 0 or 1 is returned whether the body is null or not. For example if the message body contains a List with 7 elements then ${size()} returns 7. On the other hand if the message body contains a InputStream then the result is 1, and when body is null then 0 is returned. And for String payloads such as ${size('Hello World')} then 1 is always returned.

The skip function is used for skipping the first number of elements. For example suppose you have a CSV file that contains a header line, and you want to skip this line, then you can use ${skip(1)} that then returns an Iterator that starts at the 2nd line.

The split function is as the name implies used for splitting the message body or the value (using a separator) into an array of sub elements. For example if the message body a CSV payload then using ${split(\\n)} (you need to escape the new-line character) will split this into a String[] separated by new-line. If the body is a:b:c then ${split(:)} returns a list [a, b, c]. You can also split a header or variable value: ${split($\{header.csv},-)} splits the header value using - as separator.

The sort function sorts values in natural order. If the body is a list [b, a, c] then ${sort()} returns [a, b, c]. To sort in reverse (descending) order use ${sort(true)} which returns [c, b, a].

The createEmpty function creates a new empty object. ${createEmpty(list)} returns an empty ArrayList, ${createEmpty(map)} returns an empty LinkedHashMap, ${createEmpty(set)} returns an empty LinkedHashSet, and ${createEmpty(string)} returns an empty String.

The filter function filters elements from a collection based on a predicate. For example if the body is Camel,Dog,Cheese then ${filter(${body},$\{length() > 4})} returns a list with [Camel, Cheese] (only elements with more than 4 characters). You can also filter by content: ${filter(${body},$\{contains(dog)})} returns [Dog].

The condition functions is small functions that mostly evaluates to a boolean value.

The assert function evaluates the expression and if its false or null, then an SimpleAssertionException is thrown with the given message.

The contains function is a convenient function to check if a given expression contain partly a given text (ignore case). For example given the message body is Hello big World then ${contains(world)} returns true, and ${contains(camel)} returns false.

The iif (inlined if) function is from Camel 4.18 also available as a ternary operator (predicate ? trueExp : falseExp), see further below. An example with iif could be ${iif(${header.foo} > 0,'positive','negative')}. This example is also used further below with the ternary operator. Instead of returning a fixed string as response, you can also use functions such as: ${iif(${header.foo} > 0,${body},${null})}

The remainder boolean functions are basic functions to check a value and return either true or false.

The isEmpty is primary for checking if a value is either null or empty string or empty list/map/array types. For any other values then false is returned.

The isAlpha / isAlphaNumeric and isNumeric is for checking if a value only contains A..Z or A.Z0..9, or 0..9 characters. Camel will use from the JDK Character.isLetter / Character.isLetterOrDigit, or Character.isDigit methods internally.

So ${isAlpha('Hello World')} will actually return false because there is a whitespace. However ${isAlpha('HelloWorld')} returns true.

The not function inverts a boolean value. If the body is empty then ${not()} returns true. If the body is "Hello" then ${not()} returns false. You can also negate a predicate: ${not(${body} == 'Hello')} returns false when the body is Hello, and true otherwise.

The assert function evaluates a condition and throws an exception if it fails. For example ${assert(${body} == 'Hello', 'Must be Hello')} will pass when the body is Hello, but throws a SimpleAssertionException with the message Must be Hello when the body is anything else.

The date functions is used for parsing and formatting with date and times.

For example to get the current time use ${date:now} which is returned as a java.util.Date object. And you can use ${date:millis} to get unix epoch timestamp as a long value.

If you want to format this to a String value, you can use the pattern command, such as ${date:now:hh:mm:ss}. And to get the time 8 hours in the future ${date:now+8h:hh:mm:ss}.

There is also a timezone supported function so you can say date-with-timezone:header.birthday:GMT+8:yyyy-MM-dd’T’HH:mm:ss:SSS. This will get the Date object from the header with key birthday, and format that using the given pattern in the timezone GMT+8.

You can also use date offsets with headers or exchange properties. For example ${date:header.birthday+24h:yyyyMMdd} returns the date from the header shifted forward by 24 hours. And ${date:header.birthday-10s:yyyy-MM-dd’T’HH:mm:ss:SSS} subtracts 10 seconds.

Exchange properties work the same way: ${date:exchangeProperty.birthday:yyyyMMdd} formats the property date.

The date:exchangeCreated command returns the timestamp when the current exchange was created: ${date:exchangeCreated:hh:mm:ss a} formats it as a 12-hour time with AM/PM marker.

Various functions to work with numbers.

The abs function returns the absolute value of a numeric value. It converts the input (either the message body or the result of an expression) to a long number and computes its absolute value. A few examples ${abs(-5)} returns 5, and ${abs(5)} also returns 5.

The average function calculates the average (mean) of integral numbers (not floating point). Assume message body is [10, 20, 30] (as List<Integer> or similar) then ${average()} results in 20

The ceil functions returns the value of number rounded up to the nearest integer that is greater than or equal to number. For example ${ceil(5.7)} returns 6, and ${ceil(5.1)} also returns 6.

The floor functions returns the value of number rounded down to the nearest integer that is smaller or equal to number. For example ${floor(5.7)} returns 5, and ${floor(5.1)} also returns 5.

The max and min functions in are used to find the maximum or minimum value among a set of numeric integral values. For example message body contains a list [10, 5, 30, 15] then ${max()} returns 30 and ${min()} returns 5.

The random functions returns a random number between min and max (exclusive). For example ${random(10)} returns a random number 0..9. And ${random(18,50)} returns a random number between 18..49.

The range functions returns a list of increasing numbers between min and max (exclusive). For example ${range(10)} returns the numbers 0..9. And ${range(1,10)} returns 1..9.

The sum function adds up numeric values (not floating point) and returns the result as a long. Assume message body is [10, 20, 30] (as List<Integer> or similar) then ${sum()} results in 60 You can also use the sum function to add or subtract numbers. For example if you want to add 2 to a number, you can do ${sum(${body},2)}, and likewise to subtract you use negative number, such as ${sum(${body},-2)}.

Other kind of functions.

To use OS environment variables you use the ${env.key} function, such as ${env.PATH} or ${env.HOME}, or ${env.JAVA_HOME}. Notice how the key should be in uppercase, as required by OS environment variables. For example ${env.HOME} returns the home directory path such as /home/scott.

The hash function is used for calculating a hash value of the given value. The ${hash()} would use the message body and SHA-256 as algorithm and return a hash value as String hex-decimal. For example if the body is hello then ${hash()} returns the SHA-256 hash as a hex string. You can also specify the algorithm: ${hash(${body},SHA3-256)} uses SHA3-256 instead of the default SHA-256. To hash a specific expression: ${hash($\{header.apiKey})} hashes the value of a header.

The hostname function returns the OS hostname and does not require using parenthesis, so just use ${hostname}. For example ${hostname} returns the local machine hostname such as myserver.

The null function returns a null value such as ${null}. This is useful for setting a header or variable to null: ${setHeader(foo,${null})} removes the header foo.

To use OS environment variables you can also use the ${sysenv.key} function (an alias for ${env.key}), such as ${sysenv.PATH} or ${sysenv.HOME}.

You can get the current thread id by the ${threadId} function (returns a numeric id), and the name via ${threadName} (returns the thread name such as Camel (camel-1) thread #1 - direct://start).

And you can generate unique IDs with the Camel UUID Generator by the uuid function. The generator supports different kinds default, classic, short, simple and random, such as ${uuid(random)}. For example ${uuid} returns a UUID like ID-myhost-1234-1234567890-0-1, and ${uuid(short)} returns a shorter form. You can also bind a custom UuidGenerator to the registry and use it by name: ${uuid(myGenerator)}.

To load data from classpath, you can use the load function such as $\{load(myrules.json)}. If the file is not present on classpath, then an exception is thrown. However, you can mark the file as optional as follows: $\{load(myrules.json?optional=true)}, which will return null if the file does not exists.

The string functions is various functions to work with values that are String and text based.

The capitalize function is used for capitalizing words, by upper-casing the first letter in every words. For example ${capitalize('hello world')} returns Hello World.

The concat function is used for putting together two values as a single String result. In Java, you would use the + operator such as String s = "Hello" + " world";.

The simple function works like ${concat('Hello ',${body})}. Notice how you can use nested functions so the 2nd parameter is the ${body} function. In the example we had to add a space after "Hello ", but you can also use the separator parameter, such as ${concat('Hello',${body},' ')}.

The join function is a more complex function to join together a set of values, separated by comma (by default) as a single combined String. For example if the message body contains a list of [A, B, C] then ${join()} would return A,B,C. To use semicolon as separator you would use ${join(;)}. The prefix argument can be used to prefix each value, so for example ${join(&,id=)} would return id=A&id=B&id=C.

The lowercase and uppercase functions are as the name implies used for lower and uppercasing. So ${lowercase('Hello World')} returns hello world and ${uppercase('Hello World')} returns HELLO WORLD. Without arguments, they operate on the message body: if the body is HELLO then ${lowercase()} returns hello.

You can use the normalizeWhitespace function to clean up a value by removing extra whitespaces. This is done by ensuring that there are exactly only 1 whitespace between words. And as well trimming the value for empty whitespace in the beginning and end. Suppose the message body is a String value with " Hello big World ", then ${normalizeWhitespace()} will return Hello big World.

The pad function returns a copy of the string with extra padding, if necessary, so that its total number of characters is at least the absolute value of the width parameter. If width is a positive number, then the string is padded to the right; if negative, it is padded to the left. The optional separator specifies the padding character(s) to use. If not specified, it defaults to the space character. If the message body contains foo then ${pad(${body},5)} returns "foo " and ${pad(${body},-5)} returns " foo", and ${pad(${body},-5,'@')} returns @@foo.

The replace function is used for finding a given text in a string and replacing it with another. For example the message body contains Hello a how are you, then ${replace(a,b)} returns Hello b how bre you. The replace function has special support for replacing double and single quotes.

The substring, substringBefore, and substringAfter functions are all similar functions to return a substring of a given value.

Suppose the message body contains ABCDEFGHIJK then ${substring(3)} returns DEFGHIJK, and ${substring(-3)} returns ABCDEFGH. If you want to clip the first and last character you can use ${substring(1,-1)} returning BCDEFGHIJ.

Now suppose the message body contains Hello great big World how are you.

Then ${substringBefore('World')} return "Hello great big ". And ${substringAfter('World')} returns " how are you". And ${substringBetween('great','how')} would return " big World ".

The trim function trims the value by removing leading and trailing whitespaces. So the previous example can also be trimmed by nesting the function as follows: ${trim(${substringBetween('great','how')})} which would return "big World".

And of course ${trim(' hello world ')} returns hello world. Without arguments, ${trim()} trims the message body. If the body is " hello " then ${trim()} returns hello.

The length function calculates the payload length in bytes. If the body is Hello then ${length()} returns 5. You can also pass a literal: ${length('Hello World')} returns 11.

The size function returns the number of elements in a collection or array. If the body is a List with elements [a, b, c] then ${size()} returns 3.

The quote function is making sure the returned value is enclosed in double quotes. If the value is currently in single quote, then this will be converted to double quotes.

If the message body contains Hello World then ${quote()} returns "Hello World". And using ${quote('Hi from me')} then "Hi from me" is returned.

The unquote function removes any surrounding single or double quotes from a value. If the body contains 'hello' then ${unquote()} returns hello (without the quotes).

The safeQuote function is quoting the value depending on the value type (uses the same logic as kindOfType function). In essence values that are null, boolean or numbers are not quoted, while everything else is. The safeQuote function is useful when working with JSON data.

For example when doing JSON to JSON mapping you can extract values form the source document, to be included in the output, but the values may or may not need to be quoted. Then you can use the ~> chain operator to call the safeQuote function as shown below:

Functions to work with XML and JSON payloads.

The simple language has support for working with XML and JSON data by offering functions that leverage the JSONPath, JQ, XPath languages. This also mean that you must include the required JARs on the classpath.

The jq function (JSON Query) is used for using the JQ language to obtain data from an existing JSON payload. For example given this payload:

Then ${jq(.id)} will return 123.

You can also use this for basic data mapping such as:

The jsonpath function works similar to jq but uses JSONPath. When using ${jsonpath($.id)} will also return 123.

And the data mapping can be done as follows with JSonPath instead of JQ:

The simpleJsonpath function is using Camel’s built in JSON library from camel-util-json that is a basic JSON parser. The syntax for the path is similar to Camel’s bean OGNL syntax to use a dot notation to walk down a nested structure.

Because the input JSON is not nested then the mapping example is just:

However, if there are nested JSON such as:

Then you can retrieve data from the JSON payload as follows:

You can use ?. to declare that the path is option, so if the node or attribute does not exist, then null is returned. Otherwise, Camel will throw an exception.

For example, we attempt to refer to a non-existing attribute

The optional marker can also be used sooner in the path, such as foo?.bar.age which will not fail if there are no nested bar node in the JSON payload.

The toJson function is to convert the payload to JSON as a String value. However, if the payload is already a String then no conversion happens. So suppose the payload is a Map object as follows:

Then toJson will output:

There are also pretty alternatives so when calling toPrettyJson will output:

The xpath function is for working with XML and using XPath expressions to extract data from XML payloads.

Given the following XML payload:

Then ${xpath(/order/@id)} will return 123.

And the data mapping can be done with XPath as follows:

The pretty function is used for pretty printing JSON or XML data as a String value. For example given the following JSON payload (in a single line): {"id": 123, "age": 42, "name": "scott"} then ${pretty} will output this nicely formatted:

From Camel 4.10 onwards then Camel has built-in attachment functions making it easy to obtain details from attachments stored on the Camel Message such as from HTTP file uploads, email with file attachments etc.

This requires having camel-attachments JAR on the classpath.

The attachment functions are only used with components that supports javax.attachments APIs such as camel-cxf, camel-http, camel-mail, camel-platform-http, camel-spring-ws, etc.

Suppose you are using camel-platform-http to expose a HTTP endpoint that support file uploads via http multipart, then you can use ${attachments.size} to know how many files are attached. The other functions are used to access attachment content, headers and metadata.

The key is either the filename such as ${attachmentContent(mydata.xml)} or by index (0 based) ${attachmentContent(0)}.

To know the names of the files you can use ${attachmentsKeys} which returns a Set will all the keys.

If the attached file is text based, you can access the payload via ${attachmentContentAsText(mydata.xml)} or by index ${attachmentContentAsText(0)} which returns the payload as a String value.

For example if an XML file was uploaded as mydata.xml, then you can access metadata such as ${attachment[0].name returns mydata.xml, and ${attachment[0].contentType return text/xml, and ${attachment[0].content} returns the XML payload.

If the content is binary or other formats, you can use Camels Type Converter to convert the payload into the given Object of choice, for example as a byte array: ${attachmentContentAs(mydata.xml,byte[])}

The setAttachment function is used for adding,updating or removing attachments. If the expression is null then any existing attachment is removed, such as ${setAttachment(mydata.xml,null)}.

You can add an attachment such as ${setAttachment(mydata2.xml)}, which then will use the current message body as the payload. You can also use an expression such as from a variable ${setAttachment(mydata2.xml,${variable.mydata})}.

The payload of the attachment can also refer to resources from the file system, or classpath by prefixing with resource: as follows ${setAttachment(mydata2.xml,resource:file:/inbox/mydata2.xml)}

To make the file name dynamic you can store the name in a variable such as: ${setAttachment(mydata2.xml,resource:file:${variable.attchmentName})}

From Camel 4.18 onwards then Camel has built-in base64 functions to make it easy to encode/decode.

This requires having camel-base64 JAR on the classpath.

Camel comes with functions to use camel-base64 JAR for base64 encoding and decoding.

For example ${base64Encode(Camel)} returns Q2FtZWw= and you can reverse this by ${base64Decode(Q2FtZWw=)} which then returns Camel.

If you want to encode the message body then use ${base64Encode()}, but you can also provide a nested function such as ${base64Encode(${header.myKey})} to encode a header.

From Camel 4.21 onwards then Camel has built-in HTML functions to make it easy to clean/parse and decode.

This requires having camel-jsoup JAR on the classpath.

Camel comes with functions to use camel-jsoup JAR for HTML cleaning and decoding.

For example ${htmlDecode(${header.myHtml})} will from the header with key myHtml decode the HTML (removing all tags) into a plain text, which can be fed into LLMs etc.

The ${htmlClean()} function can be used to remove unwanted tags from the HTML to sanitize untrusted HTML.

The ${htmlParse()} is used to parse the HTML into a Java org.jsoup.nodes.Document structure which is similar to org.w3c.Document but uses the JSoup API instead.

From Camel 4.21 onwards, Camel has built-in Agent-to-Agent (A2A) functions to emit task progress and extract data from A2A messages, tasks, and agent cards.

This requires having camel-a2a JAR on the classpath.

For example, ${a2a:emit('Searching documents')} emits a WORKING progress event for the current A2A task. Use ${a2a:emit(INPUT_REQUIRED,'Please provide your address')} to emit progress with an explicit task state.