TBEL Overview

ThingsBoard Expression Language (TBEL) is a lightweight scripting language purpose-built for IoT data transformation. It is a fork of MVEL with additional security constraints and built-in memory management.

TBEL is the default scripting engine for Script calculated fields, rule engine filter and transformation nodes, and other server-side scripting contexts.

Prior to TBEL, ThingsBoard used Nashorn (the JDK-bundled JavaScript engine) for server-side scripting. Nashorn was deprecated in JDK 11 and removed in JDK 15 — leaving two alternatives:

• GraalVM JavaScript — excellent but carries a heavy runtime footprint and licensing constraints that make it impractical for most self-hosted deployments.
• Remote JS Executors — Node.js processes that receive scripts over the message queue. They work, but add inter-process communication latency and consume extra system resources.

TBEL was created to provide a fast, secure, zero-dependency scripting option that runs inside the JVM without external processes.

TBEL delivers roughly 1 000× better performance for typical transformation scripts.

ThingsBoard 4.4 runs on Java 25; 4.3 and earlier required Java 17 or higher. The JDK bundles the Unicode CLDR locale database, and the CLDR data shipped with Java 21 changed the way a number of locales render dates and times. Because 4.4 jumps straight from Java 17 to Java 25, every deployment that upgrades inherits all of those changes at once. If you already run Java 21 — the release the 4.3 install guides recommended — these strings are what you see today, and nothing changes for you.

TBEL itself did not change — the Date methods simply return what the newer JDK formats. Scripts that treat a locale-formatted date as a stable string can therefore start behaving differently after the upgrade.

var d = new Date(1693962245000);
var time = d.toLocaleTimeString("en-US", "America/New_York");
// 4.3: "9:04:05 PM"  - ordinary space before PM
// 4.4: "9:04:05 PM"  - narrow no-break space (U+202F) before PM

time.endsWith(" PM"); // 4.3: true; 4.4: false
time.split(" ")[1];   // 4.3: "PM"; 4.4: fails, there is no ordinary space to split on

var options = '{"timeZone":"America/New_York","dateStyle":"full","timeStyle":"full"}';
var full = d.toLocaleString("en-US", options);
// 4.3: "Tuesday, September 5, 2023 at 9:04:05 PM Eastern Daylight Time"
// 4.4: "Tuesday, September 5, 2023, 9:04:05 PM Eastern Daylight Time"

full.split(" at ")[0]; // 4.3: "Tuesday, September 5, 2023"; 4.4: the whole string, " at " is gone

• Store and compare dates in ISO 8601. toISOString() and toJSON() follow the ISO standard rather than locale data, so their output is byte-for-byte identical on Java 17 and Java 25.
• Ask for an explicit pattern whenever the layout matters. A pattern in the options string is applied literally, so separators and the AM/PM marker no longer depend on CLDR. Localized names produced by pattern letters such as MMMM or EEEE still come from the JDK.
• Compare numbers, not formatted text. Use the numeric getters instead of matching "PM", " at " or a localized month name.

var d = new Date(1693962245000);

d.toISOString(); // "2023-09-06T01:04:05Z" - identical on 4.3 and 4.4
d.toLocaleString("en-US", '{"timeZone":"America/New_York","pattern":"yyyy-MM-dd hh:mm:ss a"}');
d.getUTCHours() >= 12; // numeric check instead of matching "PM"

• Language Guide — syntax, data types, collections, and control flow.
• Helper Functions — encoding, byte parsing, hex conversion, date/time, geofencing, and more.