Business rules scripting
Python 3
MVEL
Groovy
JavaScript
input, write to output, and use language built-ins keep working. output.put(...), output.get(...), and bracket assignment are preserved. To keep a script on the previous GraalVM engine: business rules select the engine per rule — see Script engine per rule (rules created before the move to native keep GraalVM automatically); for workflow scripts, set APPLICATION_SCRIPTENGINE_PROVIDER=graalvm on integration-designer. See Script runtime change in the 5.1 → 5.9 migration guide for the full audit.Integration designer scripting
Port a script from GraalVM to native
Use this checklist to move a JavaScript or Python script from the deprecated GraalVM engine to the native engine. Each step names one difference between the engines and links to the details. The steps apply to business rules, reusable functions, and workflow Script nodes.Find the scripts that still run on GraalVM
APPLICATION_SCRIPTENGINE_PROVIDER=graalvm is set on integration-designer. Move a reusable function together with the rules that call it. See Script engine per rule.Write to output keys, never reassign output
output = {...} is lost on GraalVM and kept on native, so a script that relied on either behavior changes after the port. Write output.key = value or output["key"] = value, which works the same on both engines. See Output is empty.Stop relying on undefined in JavaScript
undefined key as null, which clears the value in process data. Native drops the key, so the old value stays. Write null when you mean to clear a value, and guard with !== undefined when you only want to copy data that exists. See Same JavaScript rule, different output on native and GraalVM.Keep or simplify the map calls
input.get("key"), output.put("key", value), containsKey, keySet, and size work on both engines, and plain property access works on native. You can simplify Java-style code, but you don’t have to. See Java HashMap interop in JavaScript.Remove Java and Node.js access
input, output, and the other script variables. Java.type(...), Java classes, require(...), process, and global fail on native. See Can I use the Node.js crypto module in JavaScript?.Check Python imports and built-ins
os, sys, subprocess, socket, and pickle, and removes built-ins such as print, open, eval, and exec. Standard modules such as re, datetime, uuid, hashlib, and base64 work. See Python import errors and Python built-ins such as print aren’t available.Expect console.log to be silent
console.log writes nothing and print doesn’t exist. Write debug values to output while you test, then remove them. See console.log prints nothing.Make output JSON-serializable
output back as JSON. Python datetime, Decimal, and set values fail with “Failed to serialize output”, and JavaScript Map and Set values become {}. Convert them to strings, numbers, lists, or plain objects before writing them. See Failed to serialize output.Stay inside the limits
Switch the engine and test with real data
APPLICATION_SCRIPTENGINE_PROVIDER=graalvm from integration-designer, which moves every Script node at once, and test the workflows afterwards.Input and output
Scripts in FlowX receive data through bound variables. The available variables depend on the context.Available variables
instanceMetadata keys
instanceMetadata contains only instance identifiers:
instanceMetadata or any other script variable. If a business rule needs the process name as data, set it explicitly — for example as a process parameter on the start node or in the start request — since the name is static per process definition.Writing to output
Assign values to theoutput variable to persist data. Both assignment and .put() syntax work.
- JavaScript
- Python
How output is merged into process data
In process business rules,output starts empty every time the script runs. When the script finishes, FlowX merges output into the existing process data instead of replacing it. Keys you don’t write to keep their current values.
The merge works key by key:
input, change it, and write the full array back to output.
Reading from input
input is a deep copy of the process or workflow data. Changes to input are not persisted. Always write to output.
- JavaScript
- Python
Check whether a field is missing or null
A field can be missing frominput, or present with a null value. In workflows, a field that a node set to null is removed from the workflow data, so later nodes see it as missing. Check for both, so the script works whichever way the data arrives.
- JavaScript
- Python
||, !value, or if not value when 0, "", or false are valid values: they treat those values as missing.
Accessing configuration parameters
Retrieve project-level configuration parameters throughadditionalData:
Common pitfalls
Output is empty ({})
Output is empty ({})
{}:- Check your variable names.
outputmust be spelled exactly, it’s case-sensitive - Check assignment syntax. In Python on the GraalVM engine, use
output["key"] = value(bracket notation), notoutput.key = value. The default native engine accepts both forms - Don’t reassign output. On the GraalVM engine,
output = {"key": "value"}replaces the reference and is lost, because the engine reads back its ownoutputobject. The default native engine keeps the reassigned object, butoutput["key"] = "value"works on both engines, so use bracket assignment - Don’t use
return. Scripts don’t need a return statement. Write directly tooutput.
Same JavaScript rule, different output on native and GraalVM
Same JavaScript rule, different output on native and GraalVM
undefined to a key of output, at any nesting level:- Native leaves the key out of the output, so the process data keeps its current value.
- GraalVM writes the key as
null, so the current value is cleared.
undefined array item becomes null on both engines, and an explicit null clears the value on both.To get the same result on both engines, make the intent explicit instead of relying on undefined:APPLICATION_SCRIPTENGINE_PROVIDER=graalvm is set on integration-designer. In that case a key set to undefined is written as null, which clears the value that earlier nodes put in the workflow data. On the default native engine, the value is kept.Python scripts aren’t affected: None is written as null on both engines.Python import errors
Python import errors
uuid, re, hashlib, hmac, secrets, and base64 can be imported. The modules that aren’t available are listed under Python Library Support.On the default native engine (CPython), standard library modules such as uuid, re, hashlib, hmac, secrets, and base64 can be imported. Modules that reach the system, network, or files, or that inspect or generate code, are blocked together with their submodules, and fail with Import of '<module>' is not allowed in FlowX scripts. The blocked modules are os, sys, subprocess, multiprocessing, signal, ctypes, shutil, pathlib, glob, tempfile, io, socket, ssl, select, selectors, asyncio, http, urllib, ftplib, smtplib, xmlrpc, requests, httplib2, aiohttp, httpx, webbrowser, antigravity, turtle, tkinter, inspect, dis, code, codeop, compileall, importlib, pkgutil, modulefinder, types, pickle, shelve, and marshal.Python built-ins such as print aren't available
Python built-ins such as print aren't available
print, input, open, exec, eval, compile, getattr, setattr, delattr, globals, locals, vars, dir, memoryview, bytearray, exit, quit, and breakpoint. A script that calls one fails with NameError, for example NameError: name 'print' is not defined.To inspect a value while you build a script, write it to output instead of printing it, and remove the key once the script works, because output is saved to the process data:Python syntax limitations
Python syntax limitations
Java HashMap interop in JavaScript
Java HashMap interop in JavaScript
Object.keys() and spread syntax may not work as expected.input and output: get, put, set, containsKey, keySet, and size. A rule written for the GraalVM engine keeps working after you switch it to native, and plain JavaScript property access works there too.Can I use the Node.js crypto module in JavaScript?
Can I use the Node.js crypto module in JavaScript?
require doesn’t exist and Node.js modules such as crypto, fs, or http can’t be loaded. Calling require('crypto') fails with ReferenceError: require is not defined. There is no crypto global either.On the default native engine, a script sees only the standard JavaScript built-ins (JSON, Math, Date, RegExp, and similar) plus the script variables such as input and output. Node.js globals such as process and Buffer aren’t available.To hash data or generate IDs, use a Python script, where hashlib, hmac, secrets, and uuid can be imported on both engines:console.log prints nothing
console.log prints nothing
console.log, console.info, console.warn, and console.error exist, so calling them doesn’t fail, but they discard what you pass them and nothing reaches the service logs. To inspect a value while you build a script, write it to output, for example output.debugAmount = input.amount;, and remove the key once the script works.Script stopped at its time limit
Script stopped at its time limit
APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS and APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS. The same variables bound rules on the GraalVM engine. Before raising a limit, check the script for a loop that never ends or a large data model that is copied on every run. The native engine also rejects input over 1 MB. See Script size and execution limits.Failed to serialize output
Failed to serialize output
output is sent back to the service as JSON, so every value in it must be JSON-serializable. A script that writes a value JSON can’t represent fails with Failed to serialize output. In Python this happens with datetime, Decimal, and set values. In JavaScript, Map and Set values serialize as {} and function values are dropped, without an error.Convert such values before writing them to output: format dates as ISO strings with isoformat() or toISOString(), turn a Decimal into a str or float, and turn sets and maps into lists or plain objects. The GraalVM engine has no such step, so a script that works there can fail this way after switching to native.Scripts in Integration Workflows
Script nodes in Integration Workflows use the sameinput and output variables as process business rules, but the data flow is different:
- In a process business rule,
outputwrites directly to the process instance data store. - In a workflow Script node, FlowX merges
outputinto the workflow data, which is theinputfor the next node in the workflow. The data stays within the workflow until the workflow completes at an End node.
output into the workflow data. Keys the script doesn’t write keep their values, so later nodes still read data from earlier nodes, and an empty output ({}) changes nothing, as in process business rules. Write only the keys you add or change.JavaScript
JavaScript scripts run on one of two engines:Native engine (default)
Scripts run in an isolated V8 context. A script sees the standard JavaScript built-ins (JSON, Math, Date, RegExp, and similar) plus the script variables such as input and output. require, Node.js modules such as crypto or fs, and Node.js globals such as process and Buffer aren’t available. console.log and the other console methods write nothing.
GraalVM engine (opt-in)
What is GraalJS?
GraalJS is an ECMAScript compliant JavaScript implementation built on GraalVM. It supports the latest ECMAScript features and offers high performance through the GraalVM’s JIT compiler.Properties
- Supports ECMAScript 15 (2024) features including modern syntax and APIs
- Provides consistent scripting across business rules and integration designer
- Runs in a secure sandboxed environment
Limitations
On the GraalVM engine, JavaScript scripts run in a sandboxed environment. Here is a list of JavaScript features not available in the sandbox:- import.meta (ES2020)
- top-level await (ES2022)
- set operations (ES2024)
- Array.fromAsync (ES2024)
Useful links
GraalJS Documentation
ECMAScript 2024 Language Specification
Python 3
Python is a high-level, interpreted programming language known for its simplicity and readability. FlowX.AI runs Python scripts on one of two engines, selected the same way as for JavaScript: per business rule, and for workflow scripts throughAPPLICATION_SCRIPTENGINE_PROVIDER on integration-designer.
Native engine (default)
Standard library modules such asuuid, re, hashlib, hmac, secrets, and base64 can be imported. Modules that reach the system, network, or files, such as os, subprocess, socket, urllib, and io, are blocked and fail with Import of '<module>' is not allowed in FlowX scripts. Built-ins such as print, open, eval, exec, and getattr are removed. See Common pitfalls for the full lists.
Both output["key"] = value and output.key = value write to output.
GraalVM engine (opt-in)
What is GraalPy?
GraalPy is an implementation of Python that runs on the GraalVM. It offers high compatibility with standard Python (CPython) while providing the ability to run within the Java ecosystem. GraalPy supports Python 3 and provides access to a large subset of the standard Python library.Properties
- Supports Python 3.12 (Python 3.13 starting with 5.9.5) with access to most common Python libraries
- Runs up to 3x faster than Python 2.7 via Jython
- Runs in a sandboxed environment for better security
Python Library Support
On the GraalVM engine, Python 3 support in FlowX comes with a subset of the standard Python library. Python runs in a sandboxed environment and the following modules are not available: “stringprep”, “sqlite3”, “plistlib”, “getpass”, “curses”, “curses.textpad”, “curses.ascii”, “curses.panel”, “xml.parsers.expat”, “xmlrpc.client”, “xmlrpc.server”, “turtle”, “tkinter”, “test.support”, “symtable”, “pyclbr”, “msvcrt”, “winreg”, “winsound”, “grp”, “termios”, “tty”, “pty”, “syslog”, “audioop”, “msilib”, “nis”, “ossaudiodev”, “smtpd”, “spwd”, “crypt”Useful links
Python 3.12 Documentation
GraalPy Documentation
MVEL
MVEL is an expression language for Java-based applications. It provides a plethora of features and is suited for everything from the smallest property binding and extraction, to full-blown scripts.- FlowX.AI uses mvel2 - 2.5.2.Final version

