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.

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 (event id can be used for deduplication).

Business Event Types

Each business event carries its fully-qualified type in the businessEventType field, in the form camunda7:<entity>:<event>.

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
      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 (camunda7:script-violation:create) 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.

Querying the Outbox

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

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

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