Expression Cheat Sheet

Expressions and types

Formula and text expressions used in ByteChef are primarily written using SpEL (Spring Expression language) with some constraints - simple, yet powerful expression language.

SpEL is based on Java (reference documentation), but no prior Java knowledge is needed to use it.

The easiest way to learn SpEL is looking at examples which are further down this page. Some attention should be paid to data types, described in more detail in the next section.

Data types and structures

The data types used in the execution engine, SpEL expressions and data structures are Java based. These are also the data type names that appear in code completion hints. In most cases ByteChef can automatically convert between Java data types and JSON formats.

Below is the list of the most common data types. In Java types column package names are omitted for brevity, they are usually:

• Primitive types and basic objects: java.lang
• Collections: java.util
• Date/Time: java.time

Basic (primitive data types)

Objects/Maps

In ByteChef, objects are implemented as Maps, which store key-value pairs. The keys are strings, and values can be of any type. This is similar to JSON objects.

Example:

{
  "name": "John",
  "age": 30,
  "active": true
}

Arrays/Lists

In ByteChef, arrays are implemented using Lists, which are ordered collections that can contain duplicate elements. The Collection interface is the root interface for all collection types in Java, including List, Set, and Queue.

Example:

[1, 2, 3, 4, 5]
["apple", "banana", "cherry"]

Date/Time

See Handling data/time for detailed description of how to deal with date and time in ByteChef.

Expression syntax

Formula expressions

In ByteChef formula expression starts with = and ${} is used to access values.

For example:

=${httpClient_1.body.amount} + 1

will access value defined in ${httpClient_1.body.amount} nested structure and increase it for 1.

Text expressions

Also, it is allowed to write a text expression like

${httpClient_1.body.amount} is total amount

where value defined in ${httpClient_1.body.amount} nested structure will be merged with ' is total amount' literal part.

The same expression can be written as a formula expression:

=${httpClient_1.body.amount} + ' is total amount'

Basics

Most of the literals are similar to JSON ones, in fact in many cases JSON structure is valid SpEL. There are a few notable exceptions:

• Lists are written using curly braces: {"firstElement", "secondElement"}, as [] is used to access elements in array
• Strings can be quoted with either ' or "
• Field names in maps do not need to be quoted (e.g., {name: "John"} is valid SpEL, but not valid JSON)

Arithmetic Operators

The +, -, * arithmetic operators work as expected.

Conditional Operators

Relational Operators

String Operators

Method Invocations

As ByteChef uses Java types, some objects contain additional methods, but they are not allowed to be called directly on those types.

For example, this is not allowed:

'someValue'.substring(4)

Instead, use the built-in function:

substring('someValue', 4)

ByteChef provides built-in functions to help with various type operations.

Accessing Elements of a List or a Map

Attempting to access non-present elements will cause exceptions. For lists, they are thrown at runtime, and for maps, they occur before deployment during expression validation.

Filtering Lists

Special variable #this is used to operate on a single element of a list.

• Filtering all elements uses the syntax: .?[condition]
• To get the first matching element: .^[condition]
• To get the last matching element: .$[condition]

Transforming Lists

Special variable #this is used to operate on a single element of a list.

For the examples below, assume listOfPersons contains:

[
  {"name": "Alex", "age": 42}, 
  {"name": "John", "age": 24}
]

Note: toMap() function can be applied to lists of maps where each map contains key and value properties. For other list operations, see the List Functions section.

Safe Navigation

When accessing nested structures, handle null fields to avoid errors. SpEL's safe navigation operator (?.) is a shorthand for the conditional operator: someVar?.b is equivalent to someVar != null ? someVar.b : null.

Invoking Static Methods

ByteChef does not allow calling static Java methods directly.

For example, this is not allowed:

T(java.lang.Math).PI

Instead, use the equivalent built-in functions provided by ByteChef.

Chaining with Dot Operator

Type Conversions

Type conversion in ByteChef can be done either implicitly or explicitly.

Explicit Conversions

Explicit conversions are available as built-in functions. See the Type Conversion Functions section for details.

Implicit Conversions

SpEL provides many built-in implicit conversions that are also available in ByteChef. These include conversions between various numeric types and between String and other value types.

Implicit conversion occurs when an input value of one type is used in a context that expects a different type. The system will automatically attempt to convert the value to the expected type.

Common Implicit Conversions

Usage Examples

Built-in functions

Type Conversion Functions

String Functions

Date and Time Functions

List Functions

Map Functions

System Functions