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).

When Publishing Fails

Rows are handed to the publisher in the order they were written. If publishing a row fails, the dispatcher stops the cycle there. The row stays undelivered and is retried first on the next cycle. The rows behind it wait, so they are never delivered out of order. A failure is either an exception thrown by the publisher or a failed BusinessEventPublishResult it returns. During an outage of the receiving system, the outbox therefore grows until the system is back, and then drains in order. Each cycle that stops on a row logs ENGINE-00019, with the row id and how long it has been waiting.

A row the receiving system can never accept therefore holds back every business event behind it, across all processes, until it goes through. This is deliberate. Skipping it automatically would leave consumers with a gap they cannot see, such as a process-instance end for an instance whose start never arrived. Alert on ENGINE-00019, or on the eximeebpms.business.events.outbox.pending.age.oldest.seconds gauge of the monitoring extension. Fix the cause, and the outbox drains in order. Skipping a single row is an operator decision, taken knowing that its consumers will miss that event:

UPDATE ACT_RU_BUS_EVT_OBX SET PROCESSED_ = true, PROCESSED_DATE_ = CURRENT_TIMESTAMP WHERE ID_ = <row id from ENGINE-00019>;

PROCESSED_ is a boolean on PostgreSQL and H2. On Oracle, SQL Server, MySQL/MariaDB and DB2 it is numeric, so use 1 instead of true there.

Event Order

The dispatcher reads the outbox in the order rows were written, so a publisher receives the business events of a change in the order the engine recorded them. From 1.4.1-ee onward, that order matches the order in which the engine records the same occurrences in history. In particular:

• process-instance:start is always the first event of a process instance. It comes before the variable-instance:create events for the variables passed at start, the form-property:form-property-update events of a submitted start form, the job:create events of process-level timers, and anything a process-level start execution listener does. This also holds when the start event is asyncBefore: the start event is written in the transaction that starts the instance, not when the asynchronous continuation runs.
• task-instance:complete and task-instance:delete come after anything the task’s own complete/delete task listeners do (for example, setting variables). They also come after the identity-link and variable-instance:delete events for the task’s own identity links and local variables.
• Changing a task’s assignee or owner publishes identity-link-add:add-identity-link / identity-link-delete:delete-identity-link with type assignee/owner, just as candidate users and groups do.
• Standalone tasks (created with TaskService#newTask, not part of a process) publish the same task-instance:* lifecycle as user tasks, with metadata.noProcessContext set to true.

A few events deliberately differ from history:

• job:fail is published once, when a job has exhausted its retries. History records every failed attempt.
• task-instance:update is published for every task update as it happens. History records one combined update at the end of the command.
• Ending a task publishes identity-link-delete:delete-identity-link for each of its identity links. History keeps them.

This order holds within one engine transaction and between transactions that follow one another, such as a process start and a later task completion. Events of different transactions that run concurrently are not ordered relative to each other.

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
      enabled-event-types: "*"
      disabled-event-types: []
      dispatch-interval-ms: 5000
      dispatcher-batch-size: 100
      outbox-retention-ms: 604800000   # 7 days
      outbox-cleanup-interval-ms: 3600000  # 1 hour
      publisher-properties:
        kafka.bootstrap-servers: "kafka-1:9092,kafka-2:9092"
        kafka.topic: "eximeebpms.business-events"

Limiting Published Event Types

enabled is a master switch: it turns the whole mechanism on or off. To publish only some of the event types, narrow the selection with enabled-event-types and disabled-event-types.

Both take a list of tokens naming event types by their <entity>:<event> pair — the same pair that forms the fully-qualified <prefix>:<entity>:<event> type:

An event is published when enabled-event-types matches it and disabled-event-types does not — the denylist always wins. Tokens are matched case-insensitively.

Publish everything except the two highest-volume entities:

eximeebpms:
  bpm:
    business-events:
      enabled: true
      disabled-event-types:
        - variable-instance:*
        - activity-instance:*

Publish only the task lifecycle, minus assignment/update changes:

eximeebpms:
  bpm:
    business-events:
      enabled: true
      enabled-event-types:
        - task-instance:*
      disabled-event-types:
        - task-instance:update

Outside Spring Boot, the same two properties are set on the engine plugin, comma-separated — in standalone bpm-platform.xml and, with the identical syntax, in the WildFly subsystem:

<process-engine name="default">
  ...
  <plugins>
    <plugin>
      <class>org.eximeebpms.bpm.engine.impl.businessevent.BusinessEventConfigurationPlugin</class>
      <properties>
        <property name="enabled">true</property>
        <property name="publisher">kafka</property>
        <property name="disabledEventTypes">variable-instance:*,activity-instance:*</property>
      </properties>
    </plugin>
  </plugins>
</process-engine>

Two things worth knowing before narrowing the list:

• Consumers see gaps, not reordering. Disabling process-instance:start while leaving process-instance:end enabled means downstream systems receive an end event for an instance they never saw start. Delivery order among the types that are published is unaffected.
• process-instance:* does not cover the update event. Its entity is process-instance-update, not process-instance (see the type table above), so it needs its own token: process-instance-update:update.

The filter is resolved once, when the engine starts; changing it requires a restart. It has no effect on outbox rows already written — those are dispatched as normal.

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. Results are ordered by id, which follows write order. unprocessed() restricts the query to events not yet delivered. So the delivery backlog and its oldest event are:

BusinessEventQuery pending = processEngine.getBusinessEventService()
    .createBusinessEventOutboxQuery()
    .unprocessed();
long backlog = pending.count();
List<BusinessEventOutbox> oldest = pending.listPage(0, 1); // getCreatedDate() gives its age

unprocessed() and BusinessEventOutbox.getCreatedDate() are Enterprise Edition additions. Community Edition 1.4.0 has neither.