Java Action
Java Action dynamically compiles and executes Java code as an action inside the Banalytics agent JVM, using the current execution context and returning a text result for the completed action.
Add trusted Java logic to an action chain
Use Java Action when built-in actions are almost enough, but an automation rule needs a compact piece of application-specific Java logic: calculate a value, normalize text, read the current event, call an internal service, or prepare a custom result for audit and notifications.
The code runs inside the agent JVM with access to the process classpath, filesystem, network, and application services available to that process. Treat it as trusted code and keep business-critical or long-lived logic in a normal module when it grows beyond a small action.
Name the action
Set Title to the purpose of the action, for example normalize alarm text, build audit message, calculate severity, or call internal service.
Add imports and helpers only when needed
Use Imports for extra Java imports and Class properties for helper methods, constants, or small caches. Keep any static state thread-safe.
Write the method body
Java code is inserted into the generated action method. It receives engine and ctx, and it must return a string result.
Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
Title | Yes | Display name of the action. Use a name that identifies what the custom code does in rules, action groups, and event history. | None |
Imports | Optional | Additional Java import statements. Lines may be written with or without the import keyword and trailing semicolon; the compiler wrapper normalizes them before compilation. | Empty |
Class properties | Optional | Additional class-level fields or helper methods compiled into the generated action class. Use this for reusable helpers when the method body would otherwise become hard to read. | Empty |
Java code | Yes | Body of the generated action method. The method receives engine and ctx and must return a string result that becomes part of the completed action event. | Print context and return done |
Your code becomes a generated Java class
Banalytics wraps the configured imports, class-level helpers, and method body into a generated Java class. The generated method receives the Banalytics engine and execution context, then returns a string. That returned string is written into the completed action result and may be visible in event history or notification chains.
The code is compiled when the action starts. A syntax error, missing class, or unavailable compiler prevents the action from starting until the configuration is fixed.
In-process execution
The action runs inside the agent JVM, sharing classpath, services, permissions, and resource limits with the main process.
Execution context
Use the context to read the current event, values prepared by upstream tasks, or variables passed through an action group.
Text result
The method must return a string. Keep the result concise because it can be stored in history and shown to operators.
Generated class template
package com.banalytics.box.module.system.script.generated;
import com.banalytics.box.module.*;
import com.banalytics.box.module.events.*;
import java.io.*;
import java.util.*;
import java.time.*;
import java.net.*;
import java.nio.file.*;
{{imports}}
public class JavaAction_{{hash}} {
{{classProperties}}
public static String execute(BoxEngine engine, ExecutionContext ctx) throws Exception {
{{javaCode}}
}
}
Use Java for small custom action logic
Custom action logic
Small custom automation
Use Java Action when built-in actions are almost enough, but a rule needs a few lines of application-specific Java code: calculate a value, normalize text, choose a target, or write a compact custom result.
Event-aware action
Read the current event from the execution context and build a result that is useful for audit, notifications, or later troubleshooting. For example, read the current event and return a short summary.
Context mutation before another action
Store calculated values in the execution context when the same action chain or group needs to pass additional data to later logic.
Integration and diagnostics
Service integration inside the JVM
Use engine to reach application services or beans when the integration should run in-process and share the agent classpath, configuration, and permissions.
Manual diagnostic action
Create a temporary action that prints or returns information about the current engine state, selected objects, paths, or environment. Remove or disable diagnostic code after use.
Lightweight file or network operation
Default imports include common IO, collections, time, URL, and path APIs, so short local checks or controlled HTTP/file operations can be implemented without a separate module.
Code organization
Reusable helper code
Put helper methods, constants, or small caches into Class properties when several lines of logic would make Java code hard to read. Keep any static state thread-safe.
Prototype before a module
Use Java Action to validate a small idea quickly, then move stable or business-critical logic into a normal module where it can be tested, reviewed, versioned, and protected by clearer permissions.
Operational notes
Method body, not full class
Java code is a method body, not a full Java class. It must return a string. Returning a null value is allowed by Java but makes the action event less useful.
Default imports are already available
The generated method receives BoxEngine engine and ExecutionContext ctx. Common Banalytics event classes plus IO, collections, time, network, and path APIs are imported by default.
Compilation happens on start
Imports, Class properties, and Java code are compiled when the action starts. A syntax error or missing class prevents startup until the configuration is fixed.
JDK is required
Compilation requires a JDK with the Java compiler available, not only a JRE. The current compiler settings use Java 20 source and target compatibility.
Compiled classes are cached
Compiled classes are cached under the agent application home in java-cache and reused by a hash of the configured code. Changing the code creates a new compiled version.
Action results are visible
The action emits starting and completed action events. The returned string becomes the completed event result and may be visible in event history or notification chains.
Treat code as trusted
The code runs inside the agent JVM with access to process permissions, filesystem, network, and application services. Do not run unreviewed code from untrusted users.
Avoid heavy work in noisy rules
Avoid long-running, blocking, or memory-heavy code in high-frequency rules. Slow custom Java can delay action execution and excessive allocations can affect the whole agent.
Use purpose-built tools when appropriate
Prefer SQL Action, Command Line Action, Process, or a dedicated module when the operation is large, security-sensitive, needs retries, needs parameter binding, or must be maintained for a long time.