Knowledge Base
Knowledge Base
  • Login
Font Size:
Ask Joget AI

BeanShell Audit Trail Hook

Introduction

The BeanShell Audit Trail Hook plugin allows developers to execute custom BeanShell logic whenever specific Joget audit events occur. It works by intercepting runtime audit trail events such as form submissions, workflow executions, assignments, workflow variable updates, and tool executions.

This plugin is useful for implementing custom runtime automation, conditional logic, integrations, validations, monitoring, and workflow-related behaviors without modifying the Joget core code.

How Does It Work?

The plugin listens to Joget audit trail events and executes a BeanShell script when the event matches the configured filters.

The flow is:

  1. User submits form.
  2. Joget emits an audit event.
  3. Filters are evaluated.
  4. BeanShell executes.

When the script runs, the following variables are automatically available:

  1. clazz: Fully qualified Java class name that produced the event
  2. method: Method name that produced the event
  3. message: Audit message string
  4. appId: Joget App ID
  5. args[]: Raw method arguments as an array
  6. argsMap: Named method arguments (if Args Key Names is configured)

Configuring The BeanShell Audit Trail Hook

You may configure the plugin in Plugin Default Properties:

  1. Go to Plugin Default Properties.
  2. Select Set Plugin Default Properties.
  3. Choose BeanShell Audit Trail Hook.
  4. Configure the BeanShell script and optional filters.
  5. Click Submit.

Configuration Properties

  • BeanShell Script: The BeanShell code to execute when a matching audit event occurs. All Java classes must be explicitly imported.
    • import org.joget.commons.util.LogUtil;
    • LogUtil.info("AuditHook", "Class: " + clazz);
    • LogUtil.info("AuditHook", "Method: " + method);
    • LogUtil.info("AuditHook", "Message: " + message);
    • LogUtil.info("AuditHook", "App ID: " + appId);
  • Class Regex Filter: Filters events based on the fully qualified Java class name. The script runs only if the class name matches this regex.

Examples:

 
 

org\.joget\.apps\.form\.service\.FormServiceImpl

Use case: Intercept form persistence events, target workflow-related classes, narrow plugin execution scope.

  • Method Regex Filter: Filters events based on the method name. The script runs only if the method name matches this regex.

Examples:

store ← exact method

Use case: Intercept save operations, workflow start methods, or assignment-related methods.

  • Message Contains: Filters events using simple substring matching against the audit message. This is not a regex — it is a plain text match.

Examples: success, deleted, form submitted

Use case: Narrow execution when class and method filters are too broad.

  • App ID Contains: Plain text match for auditTrail appId.

Examples: crm, sales, helpdesk

Use case: Run logic only within selected apps, or isolate behavior in multi-app environments.

  • Args Key Names: Maps raw method arguments into named keys for easier access inside BeanShell. Raw arguments are available as args[0], args[1], etc. This field lets you map them into argsMap with meaningful names.
  • Fail On Script Error: Controls exception handling when the BeanShell script throws an error.

Use unchecked for safer production behavior. Use checked for strict debugging or enforced validation.

  • Important: All Filters Use AND Logic

All configured filters are evaluated together with AND. The script only runs if every configured filter matches. If any one filter fails, the script does not execute.

  • Example Configuration

Script runs only when class is a service, method is create or update, message mentions success, and app is sales:

    • Class Regex Filter: org\.joget\..*Service.*
    • Method Regex Filter: (create|update)
    • Message Contains: success
    • App ID Contains: sales
    • Args Key Names: id,status,payload
    • Fail On Script Error: unchecked
Created by Nabila Jahan Last modified by Debanraj Ravindran on Jun 26, 2026
Tags:
Previous Wflow Storage Permission Check NextControlled By Multiple Manage Permission Keys