Business Events let the process engine publish a stream of domain-level occurrences — a task was completed, a variable changed, a process instance ended — to systems outside the engine, without coupling the engine’s own transaction to the availability of those systems.

For the exact fields carried by each event type’s payload, see Business Event Field Reference.

How It Works

Business Events use the transactional outbox pattern:

1. When an event-worthy change happens (e.g., a task is completed), the engine writes a row describing it to the ACT_RU_BUS_EVT_OBX table, in the same database transaction as the change itself.
2. A background dispatcher periodically reads batches of undelivered rows from the outbox and hands them to the configured publisher.
3. Once a publisher confirms delivery, the corresponding outbox rows are marked delivered; a separate cleanup job removes delivered rows past their retention period.

Because the outbox write is part of the same transaction as the business change, an event is never recorded for a change that didn’t commit, and a committed change never silently fails to produce its event — delivery to the publisher is a separate, retried concern. This gives at-least-once delivery to downstream systems: consumers should treat delivery as idempotent (the metadata.uuid field described below can be used for deduplication).

Event Envelope

What a publisher (e.g. the kafka publisher, or a custom BusinessEventPublisher) actually receives is an Event envelope wrapping the business event, not the business event object directly:

{
  "metadata": {
    "timestamp": "2026-07-29T10:15:23.456+00:00",
    "uuid": "1c1a9e2e-2a34-4b7d-9f0a-6e3d3a2b9c11",
    "type": "bpms:task-instance:complete",
    "version": "1.0",
    "origin": "bpms",
    "correlationId": null,
    "processInstanceId": "3f2c...",
    "processDefinitionKey": "invoice-approval",
    "noProcessContext": false
  },
  "payload": "{\"id\":\"...\",\"processInstanceId\":\"3f2c...\", ... }"
}

Business Event Types

Each business event carries its fully-qualified type in the businessEventType field of its payload (and in metadata.type of the envelope), in the form <prefix>:<entity>:<event>. The default prefix is bpms and is configurable; examples below use the default.

For the exact payload fields behind each row, follow the links to the Business Event Field Reference.

Process & Task Lifecycle

Variables & Identity Links

Jobs, Batches & External Tasks

Incidents & Decisions

Forms & Audit Trail

Configuration

Business Events are configured under the eximeebpms.bpm.business-events prefix and are disabled by default:

eximeebpms:
  bpm:
    business-events:
      enabled: true
      publisher: kafka
      prefix: bpms
      business-event-dispatch-interval-ms: 5000
      business-event-dispatcher-batch-size: 100
      business-event-outbox-retention-ms: 604800000   # 7 days
      business-event-outbox-cleanup-interval-ms: 3600000  # 1 hour
      publisher-properties:
        kafka.bootstrap-servers: "kafka-1:9092,kafka-2:9092"
        kafka.topic: "eximeebpms.business-events"

Built-in Publishers

noop (default)

Writes to the outbox but never dispatches anywhere. Useful for exercising the outbox and cleanup mechanics without wiring an external system.

kafka

Publishes events to an Apache Kafka topic. Enable with publisher: kafka and configure under publisher-properties:

Writing a Custom Publisher

To deliver events somewhere other than Kafka (a webhook, a message broker, a SIEM ingestion endpoint), implement the BusinessEventPublisher SPI:

package org.eximeebpms.bpm.commons.eventbus;

public interface BusinessEventPublisher extends AutoCloseable {

  String getName();

  default void init(Map<String, String> properties) {
  }

  BusinessEventPublishResult publish(Event event);

  @Override
  default void close() {
  }
}

Register the implementation so it’s discoverable under its getName() value, then set publisher: <name> in configuration. init(Map<String, String>) receives whatever is configured under publisher-properties for that publisher name.

Script Guard / SIEM Integration

As of 1.2.19-ee, Script Guard violations are published as business events (bpms:script-violation:create by default) through this same mechanism. This means routing Script Guard violations to a SIEM is a matter of enabling Business Events and pointing the configured publisher at your SIEM ingestion endpoint (via the Kafka publisher, or a custom BusinessEventPublisher implementation) — no separate integration is required. The same applies to the user operation log events introduced in 1.3.1-ee, which give a SIEM a real-time feed of administrative actions (task assignment/suspension, batch/job/deployment operations) in addition to the periodic ACT_HI_OP_LOG table.

Querying the Outbox

The engine exposes a query API over the outbox via BusinessEventService:

processEngine.getBusinessEventService()
    .createBusinessEventOutboxQuery()
    .processInstanceId(processInstanceId)
    .eventType("bpms:script-violation:create")
    .list();

This is primarily useful for diagnostics and for verifying delivery independently of the configured publisher.