Skip to main content

ShellUtil

ShellUtil provides a method to execute shell (OS-level) commands from within a workflow script. Use it to invoke external programs, scripts, or system utilities as part of a workflow step.

warning

Requires Unsafe Utilities ShellUtil is only available when Unsafe Utilities are enabled. To enable them, go to System Settings → Workflow → Compiler and turn on Unsafe utilities.

Unsafe utilities allow scripts to execute arbitrary OS commands. Only enable this on servers where all workflow developers are trusted, as it grants significant access to the underlying operating system.

Methods​

exec(...command: String[]): Integer​

Executes a shell command and waits for it to complete.

Parameters:

ParameterTypeDescription
commandString...The program name followed by its arguments, each as a separate string

Returns: The exit code of the process. By convention:

  • 0 — The command completed successfully
  • Non-zero — The command failed (the specific meaning depends on the program)
  • -1 — An exception occurred while starting or running the process

Behavior:

  • Standard output (stdout) from the command is logged at INFO level in the node's execution log.
  • Standard error (stderr) from the command is logged at ERROR level.
  • The method blocks until the process finishes (or an error occurs).

Examples​

Run an external script​

var exitCode = ShellUtil.exec("/bin/bash", "/opt/scripts/cleanup.sh", "--target", "/data/tmp");
if (exitCode != 0) {
  throw "Cleanup script failed with exit code: " + exitCode;
}

Copy a file on Windows​

ShellUtil.exec("cmd.exe", "/c", "copy", "C:\\data\\input.csv", "C:\\archive\\input.csv");

Run a Python script​

var exitCode = ShellUtil.exec("python3", "/opt/scripts/process.py", "--input", properties.get("FILE_PATH"));
if (exitCode != 0) {
  throw "Python script failed";
}

Check a return code​

var result = ShellUtil.exec("ping", "-c", "1", "192.168.1.100");
if (result == 0) {
  properties.set("SERVER_REACHABLE", "true");
} else {
  properties.set("SERVER_REACHABLE", "false");
}

Security Notes​

  • Commands run as the same OS user that is running the B2Win Suite server process. Ensure this user has only the permissions it needs.
  • Avoid passing unsanitized user input directly into shell commands to prevent command injection.
  • On Windows, use cmd.exe /c <command> to run batch commands or built-in shell features.
  • On Linux/macOS, use /bin/bash or /bin/sh to run shell scripts.